/ Hex Artifact Content
Login

Artifact 63b07f76731f2b1e55c48fdb9f0508dcc6fbe3971010b8612ffd847c3c56d9a1:


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 4c 4f 43 4b  fine SQLITE_LOCK
59f0: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  ED_VTAB         
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5a10: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64  ED |  (2<<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 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
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 31 3c 3c 38 29 29 0a 23  Y   |  (1<<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 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
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 32 3c 3c 38 29 29 0a  SY   |  (2<<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 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5c00: 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20 20  SEQUENCE        
5c10: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5c20: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5c30: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5c40: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5c50: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5c60: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5c70: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5c80: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5c90: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ca0: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5cc0: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5cd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5ce0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5d00: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5d10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5d20: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5d30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d40: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e  _READONLY_CANTIN
5d50: 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  IT       (SQLITE
5d60: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c  _READONLY | (5<<
5d70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d80: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45  TE_READONLY_DIRE
5d90: 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49  CTORY      (SQLI
5da0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36  TE_READONLY | (6
5db0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5dc0: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5dd0: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5de0: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5df0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5e10: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5e20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5e30: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5e40: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e50: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5e60: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e70: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5e80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5e90: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5ea0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5eb0: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5ec0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ed0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5ee0: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5ef0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5f00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5f10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5f20: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5f30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f40: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5f50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5f60: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5f70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f80: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5fa0: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5fc0: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fe0: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5ff0: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
6000: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
6010: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6020: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
6030: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
6040: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
6050: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
6060: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6070: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
6080: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6090: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
60a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
60b0: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
60c0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
60d0: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
60e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
60f0: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
6100: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
6110: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
6130: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
6140: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
6150: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
6160: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
6170: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
6180: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
6190: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  H | (1<<8)).#def
61a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f  ine SQLITE_OK_LO
61b0: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20  AD_PERMANENTLY  
61c0: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     (SQLITE_OK | 
61d0: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
61e0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
61f0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
6200: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
6210: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
6220: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
6230: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
6240: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
6250: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
6260: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
6270: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
6280: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
6290: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
62a0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
62b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
62c0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
62d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62e0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
62f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6310: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
6320: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6330: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
6340: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6350: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6360: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
6370: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6380: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
6390: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
63a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63b0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
63c0: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
63d0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
63e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63f0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6410: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
6420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6430: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
6440: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6450: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
6460: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6470: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6480: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6490: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
64a0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
64b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
64c0: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
64d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64e0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
64f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6510: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
6520: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
6530: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6550: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
6560: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6570: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6580: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6590: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
65a0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
65b0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
65c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65d0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
65e0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
65f0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6600: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6610: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
6620: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
6630: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6640: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6650: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
6660: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6670: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6680: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6690: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
66a0: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
66b0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
66c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66d0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
66e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
66f0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6700: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6710: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6720: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
6730: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
6740: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6750: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6770: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6780: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6790: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
67a0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
67c0: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
67d0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
67e0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
67f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6810: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
6820: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
6830: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6840: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
6850: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6860: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6870: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6880: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6890: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
68a0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
68b0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
68c0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
68d0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
68e0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
68f0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
6900: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
6910: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
6920: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
6930: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
6940: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
6950: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
6960: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6970: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6980: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6990: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
69a0: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
69b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
69c0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
69d0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
69e0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
69f0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6a00: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6a10: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6a20: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6a30: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6a40: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6a50: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6a60: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6a70: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6a80: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6a90: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6aa0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6ab0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6ac0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6ad0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6ae0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6af0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6b00: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6b10: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6b20: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6b30: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6b40: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6b50: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6b60: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6b70: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6b80: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6b90: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6ba0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6bb0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6bc0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6bd0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6be0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6bf0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6c00: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6c10: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6c20: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6c30: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6c40: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6c50: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6c60: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6c70: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6c80: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6c90: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6ca0: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6cb0: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6cc0: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6cd0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6ce0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6cf0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6d00: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
6d10: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6d20: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6d30: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6d40: 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  es that a file c
6d50: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6d60: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6d70: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
6d80: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
6d90: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
6da0: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
6db0: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
6dc0: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6dd0: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6de0: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6df0: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6e00: 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eges..**.** The 
6e10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
6e20: 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  CH_ATOMIC proper
6e30: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ty means that th
6e40: 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20  e underlying.** 
6e50: 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f  filesystem suppo
6e60: 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70  rts doing multip
6e70: 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  le write operati
6e80: 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77  ons atomically w
6e90: 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69  hen those.** wri
6ea0: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
6eb0: 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b  e bracketed by [
6ec0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
6ed0: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
6ee0: 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
6ef0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
6f00: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23  MIC_WRITE]..*/.#
6f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6f20: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6f30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6f40: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6f50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6f60: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
6f70: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
6f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6f90: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
6fa0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6fb0: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
6fc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6fd0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6fe0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
6ff0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7000: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
7010: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
7020: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7030: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
7040: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7050: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
7060: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7070: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
7080: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
7090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
70a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
70b0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
70c0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
70d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
70e0: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
70f0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
7100: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7110: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
7120: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7130: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
7140: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
7150: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
7160: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
7170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7180: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
7190: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
71a0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
71b0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
71c0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
71d0: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
71e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
71f0: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
7200: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
7210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7220: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
7230: 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78 30  IC           0x0
7240: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
7250: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
7260: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
7270: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
7280: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
7290: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
72a0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
72b0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
72c0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
72d0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
72e0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
72f0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
7300: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7310: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
7320: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
7330: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
7340: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
7350: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
7360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7370: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
7380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7390: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
73a0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
73b0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
73c0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
73d0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
73e0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
73f0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
7400: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
7410: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
7420: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
7430: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7440: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
7450: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
7460: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
7470: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
7480: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
7490: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
74a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
74b0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
74c0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
74d0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
74e0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
74f0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
7500: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
7510: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
7520: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
7530: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
7540: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
7550: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
7560: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7570: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
7580: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
7590: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
75a0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
75b0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
75c0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
75d0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
75e0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
75f0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7600: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
7610: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
7620: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
7630: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
7640: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
7650: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
7660: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
7670: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7680: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
7690: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
76a0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
76b0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
76c0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
76d0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
76e0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
76f0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
7700: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
7710: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
7720: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
7730: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
7740: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7750: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7760: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7770: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7780: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7790: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
77a0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
77b0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
77c0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
77d0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
77e0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
77f0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7800: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
7810: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
7820: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
7830: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
7840: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
7850: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7860: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7870: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7880: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7890: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
78a0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
78b0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
78c0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
78d0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
78e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
78f0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7900: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
7910: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
7920: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
7930: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
7940: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7950: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
7960: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7970: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7980: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7990: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
79a0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
79b0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
79c0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
79d0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
79e0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
79f0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7a00: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
7a10: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
7a20: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
7a30: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7a40: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7a50: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
7a60: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7a70: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7a80: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7a90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7aa0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7ab0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7ac0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7ad0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7ae0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7af0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7b00: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7b10: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7b20: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7b30: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7b40: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7b50: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
7b60: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7b70: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7b80: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7b90: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7ba0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7bb0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7bc0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7bd0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7be0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7bf0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7c00: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7c10: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7c20: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7c30: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7c40: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7c50: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
7c60: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7c70: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7c80: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7c90: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7ca0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7cb0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7cc0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7cd0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7ce0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7cf0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7d00: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7d10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7d20: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7d30: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7d40: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7d50: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
7d60: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7d70: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7d80: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7d90: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7da0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7db0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7dc0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7dd0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7de0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7df0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7e00: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7e10: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7e20: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7e30: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7e40: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7e50: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
7e60: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7e70: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7e80: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7e90: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7ea0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7eb0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7ec0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7ed0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7ee0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7ef0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7f00: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7f10: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7f20: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7f30: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7f40: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7f50: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
7f60: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
7f70: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
7f80: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
7f90: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
7fa0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
7fb0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7fc0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7fd0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7fe0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7ff0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
8000: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
8010: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
8020: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
8030: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
8040: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
8050: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
8060: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8070: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
8080: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8090: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
80a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
80b0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
80c0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
80d0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
80e0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
80f0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
8100: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
8110: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
8120: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
8130: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
8140: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
8150: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
8160: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
8170: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
8180: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
8190: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
81a0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
81b0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
81c0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
81d0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
81e0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
81f0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
8200: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
8210: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
8220: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
8230: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
8240: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
8250: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
8260: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
8270: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8280: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
8290: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
82a0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
82b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
82c0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
82d0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
82e0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
82f0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
8300: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
8310: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
8320: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
8330: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
8340: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
8350: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
8360: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
8370: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
8380: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
8390: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
83a0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
83b0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
83c0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
83d0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
83e0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
83f0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
8400: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
8410: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
8420: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
8430: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
8440: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
8450: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
8460: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
8470: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
8480: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
8490: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
84a0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
84b0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
84c0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
84d0: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
84e0: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
84f0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
8500: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
8510: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
8520: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
8530: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
8540: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8550: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
8560: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8570: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8580: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8590: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
85a0: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
85b0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
85c0: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
85d0: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
85e0: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
85f0: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
8600: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
8610: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
8620: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
8630: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
8640: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
8650: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
8660: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8670: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8680: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8690: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
86a0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
86b0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
86c0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
86d0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
86e0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
86f0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
8700: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
8710: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
8720: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
8730: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
8740: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
8750: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
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 35 31  E_IOCAP_ATOMIC51
8780: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8790: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
87a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
87c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
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 38  TE_IOCAP_ATOMIC8
8800: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8810: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8820: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
8830: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8840: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
8850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8860: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8880: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8890: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
88a0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c  EQUENTIAL].** <l
88b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
88c0: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
88d0: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20  N_OPEN].** <li> 
88e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
88f0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
8900: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
8910: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
8920: 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  LE].** <li> [SQL
8930: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
8940: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ATOMIC].** </ul>
8950: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
8960: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8970: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8980: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8990: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
89a0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
89b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
89c0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
89d0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
89e0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
89f0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
8a00: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8a10: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8a20: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8a30: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8a40: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8a50: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8a60: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8a70: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8a80: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8a90: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8aa0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8ab0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8ac0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8ad0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8ae0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8af0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8b00: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8b10: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8b20: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8b30: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8b40: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8b50: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8b60: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8b70: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8b80: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8b90: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8ba0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8bb0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8bc0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8bd0: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8be0: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8bf0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8c00: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8c10: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8c20: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8c30: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8c40: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8c50: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8c60: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8c70: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8c80: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8c90: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8ca0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8cb0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8cc0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8cd0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8ce0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8cf0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8d00: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8d10: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8d20: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8d30: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8d40: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8d50: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8d60: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8d70: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8d80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8d90: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8da0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8db0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8dc0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8dd0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8de0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8df0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8e00: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8e10: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8e20: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8e30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8e40: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8e50: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8e60: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8e70: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8e80: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8e90: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8ea0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8eb0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8ec0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8ed0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8ee0: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8ef0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8f00: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8f10: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8f20: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8f30: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8f40: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8f50: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8f60: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
8f70: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8f80: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8f90: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
8fa0: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
8fb0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
8fc0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
8fd0: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
8fe0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
8ff0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
9000: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
9010: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
9020: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
9030: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
9040: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
9050: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
9060: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
9070: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
9080: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9090: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
90a0: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
90b0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
90c0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
90d0: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
90e0: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
90f0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
9100: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
9110: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
9120: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
9130: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
9140: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
9150: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
9160: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
9170: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
9180: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
9190: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
91a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
91b0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
91c0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
91d0: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
91e0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
91f0: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
9200: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
9210: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
9220: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
9230: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
9240: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
9250: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
9260: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
9270: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
9280: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9290: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
92a0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
92b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
92c0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
92d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
92e0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
92f0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9300: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
9310: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
9320: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
9330: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
9340: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
9350: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
9360: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
9370: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
9380: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
9390: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
93a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
93b0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
93c0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
93d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
93e0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
93f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
9400: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
9410: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
9420: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
9430: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
9440: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
9450: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
9460: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
9470: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
9480: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
9490: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
94a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
94b0: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
94c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
94d0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
94e0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
94f0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
9500: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
9510: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
9520: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9530: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
9540: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
9550: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
9560: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
9570: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
9580: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
9590: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
95a0: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
95b0: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
95c0: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
95d0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
95e0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
95f0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
9600: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
9610: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
9620: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9630: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
9640: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9650: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9660: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
9670: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9680: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
9690: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
96a0: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
96b0: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
96c0: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
96d0: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
96e0: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
96f0: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
9700: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
9710: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
9720: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9730: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
9740: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
9750: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
9760: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
9770: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
9780: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
9790: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
97a0: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
97b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
97c0: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
97d0: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
97e0: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
97f0: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
9800: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
9810: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
9820: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
9830: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
9840: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9850: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9860: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9870: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9880: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
9890: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
98a0: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
98b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
98c0: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
98d0: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
98e0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
98f0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
9900: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
9910: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9920: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
9930: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9940: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
9950: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
9960: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
9970: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
9980: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
9990: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
99a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
99b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
99c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
99d0: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65   journal file (e
99e0: 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f  ither.** the [ro
99f0: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20  llback journal] 
9a00: 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68  or the [write-ah
9a10: 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20  ead log]) for a 
9a20: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9a30: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9a40: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
9a50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9a60: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9a70: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9a80: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9a90: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
9aa0: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
9ab0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9ac0: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
9ad0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9ae0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9af0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9b00: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
9b10: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
9b20: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
9b30: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
9b40: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
9b50: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
9b60: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
9b70: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
9b80: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
9b90: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
9ba0: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
9bb0: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
9bc0: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
9bd0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9be0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9bf0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
9c00: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
9c10: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
9c20: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
9c30: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
9c40: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
9c50: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
9c60: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9c70: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
9c80: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
9c90: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
9ca0: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
9cb0: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
9cc0: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
9cd0: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
9ce0: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
9cf0: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
9d00: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9d10: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
9d20: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
9d30: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
9d40: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
9d50: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
9d60: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9d70: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9d80: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
9d90: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
9da0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9db0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9dc0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9dd0: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
9de0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
9df0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9e00: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9e10: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9e20: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
9e30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
9e40: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
9e50: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9e60: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
9e70: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
9e80: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9e90: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
9ea0: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
9eb0: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
9ec0: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
9ed0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
9ee0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
9ef0: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
9f00: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
9f10: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
9f20: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
9f30: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
9f40: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
9f50: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
9f60: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
9f70: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
9f80: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9f90: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9fa0: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9fb0: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
9fc0: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
9fd0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9fe0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9ff0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
a000: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a010: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
a020: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
a030: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
a040: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
a050: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a060: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
a070: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
a080: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
a090: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
a0a0: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
a0b0: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
a0c0: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
a0d0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
a0e0: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
a0f0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
a100: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
a110: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
a120: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
a130: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
a140: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
a150: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
a160: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
a170: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
a180: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
a190: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
a1a0: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
a1b0: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
a1c0: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
a1d0: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
a1e0: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
a1f0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
a200: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
a210: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
a220: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
a230: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
a240: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
a250: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
a260: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
a270: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
a280: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
a290: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
a2a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a2b0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
a2c0: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
a2d0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
a2e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
a2f0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
a300: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
a310: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
a320: 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72 65  er is the new re
a330: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
a340: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
a350: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
a360: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
a370: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
a380: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
a390: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
a3a0: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
a3b0: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
a3c0: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
a3d0: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
a3e0: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
a3f0: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
a400: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
a410: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
a420: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
a430: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
a440: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
a450: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
a460: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a470: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
a480: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a490: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
a4a0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a4b0: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a4c0: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
a4d0: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
a4e0: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
a4f0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
a500: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
a510: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64  te ahead log and
a520: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
a530: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
a540: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
a550: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
a560: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
a570: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
a580: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
a590: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
a5a0: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
a5b0: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a5c0: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
a5d0: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
a5e0: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
a5f0: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
a600: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
a610: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
a620: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
a630: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
a640: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
a650: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
a660: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
a670: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
a680: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
a690: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
a6a0: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
a6b0: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
a6c0: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
a6d0: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
a6e0: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
a6f0: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
a700: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a710: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a720: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a730: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a740: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a750: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a760: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a770: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
a780: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a790: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a7a0: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
a7b0: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
a7c0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a7d0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a7e0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a7f0: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
a800: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
a810: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a820: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a830: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a840: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a850: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a860: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
a870: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a880: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a890: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
a8a0: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
a8b0: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
a8c0: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
a8d0: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
a8e0: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
a8f0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
a900: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
a910: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
a920: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
a930: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
a940: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a950: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a960: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a970: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
a980: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
a990: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
a9a0: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
a9b0: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
a9c0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
a9d0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a9e0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
a9f0: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
aa00: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
aa10: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
aa20: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
aa30: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
aa40: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
aa50: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
aa60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
aa70: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
aa80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa90: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
aaa0: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
aab0: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
aac0: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
aad0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
aae0: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
aaf0: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
ab00: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
ab10: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
ab20: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
ab30: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
ab40: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
ab50: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
ab60: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
ab70: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
ab80: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
ab90: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
aba0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
abb0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
abc0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
abd0: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
abe0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
abf0: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
ac00: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
ac10: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
ac20: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
ac30: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
ac40: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
ac50: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
ac60: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
ac70: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
ac80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
ac90: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
aca0: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
acb0: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
acc0: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
acd0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
ace0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
acf0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
ad00: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
ad10: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
ad20: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
ad30: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
ad40: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
ad50: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
ad60: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
ad70: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
ad80: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
ad90: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
ada0: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
adb0: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
adc0: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
add0: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
ade0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
adf0: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
ae00: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
ae10: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
ae20: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
ae30: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
ae40: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
ae50: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
ae60: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ae70: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a  L_VFS_POINTER]].
ae80: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
ae90: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
aea0: 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  R] opcode finds 
aeb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
aec0: 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56   top-level.** [V
aed0: 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20  FSes] currently 
aee0: 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61  in use.  ^(The a
aef0: 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20  rgument X in.** 
af00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
af10: 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46  trol(db,SQLITE_F
af20: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
af30: 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f  ,X) must be.** o
af40: 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33  f type "[sqlite3
af50: 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73  _vfs] **".  This
af60: 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65   opcodes will se
af70: 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69  t *X.** to a poi
af80: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d  nter to the top-
af90: 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20  level VFS.)^.** 
afa0: 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20  ^When there are 
afb0: 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69  multiple VFS shi
afc0: 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c  ms in the stack,
afd0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e   this opcode fin
afe0: 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d  ds the.** upper-
aff0: 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a  most shim only..
b000: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b010: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b020: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
b030: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
b040: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
b050: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
b060: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
b070: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
b080: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
b090: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
b0a0: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
b0b0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
b0c0: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
b0d0: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
b0e0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
b0f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
b100: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
b110: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b120: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
b130: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
b140: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
b150: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
b160: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
b170: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
b180: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
b190: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
b1a0: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
b1b0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
b1c0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
b1d0: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
b1e0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
b1f0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
b200: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
b210: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
b220: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b230: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
b240: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
b250: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
b260: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
b270: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
b280: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
b290: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b2a0: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
b2b0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
b2c0: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
b2d0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
b2e0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
b2f0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
b300: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
b310: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
b320: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
b330: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b340: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b350: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
b360: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
b370: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
b380: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
b390: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
b3a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b3b0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
b3c0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b3d0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
b3e0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
b3f0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
b400: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
b410: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
b420: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
b430: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
b440: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
b450: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72  d statement if r
b460: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20  esult string is 
b470: 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65  NULL, or that re
b480: 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20  turns a copy.** 
b490: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74  of the result st
b4a0: 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69  ring if the stri
b4b0: 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a  ng is non-NULL..
b4c0: 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
b4d0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b4e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b4f0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
b500: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
b510: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
b520: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
b530: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
b540: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
b550: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
b560: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
b570: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
b580: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
b590: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
b5a0: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
b5b0: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
b5c0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b5d0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b5e0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
b5f0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
b600: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
b610: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
b620: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
b630: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
b640: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
b650: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
b660: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b670: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b680: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
b690: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b6a0: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
b6b0: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
b6c0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
b6d0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
b6e0: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
b6f0: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
b700: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
b710: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
b720: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
b730: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
b740: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
b750: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
b760: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
b770: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
b780: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
b790: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
b7a0: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
b7b0: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
b7c0: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
b7d0: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
b7e0: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
b7f0: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
b800: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
b810: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
b820: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
b830: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
b840: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
b850: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
b860: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
b870: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
b880: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
b890: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
b8a0: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
b8b0: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
b8c0: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
b8d0: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
b8e0: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
b8f0: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
b900: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
b910: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
b920: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b930: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
b940: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
b950: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
b960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b970: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
b980: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
b990: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
b9a0: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
b9b0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
b9c0: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
b9d0: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
b9e0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
b9f0: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
ba00: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
ba10: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
ba20: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
ba30: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
ba40: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
ba50: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
ba60: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
ba70: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
ba80: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
ba90: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
baa0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
bab0: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
bac0: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
bad0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
bae0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
baf0: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
bb00: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
bb10: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bb20: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
bb30: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bb40: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
bb50: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
bb60: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
bb70: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
bb80: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
bb90: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
bba0: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
bbb0: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
bbc0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
bbd0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
bbe0: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
bbf0: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
bc00: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
bc10: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
bc20: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
bc30: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
bc40: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
bc50: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
bc60: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
bc70: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
bc80: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
bc90: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
bca0: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
bcb0: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
bcc0: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
bcd0: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
bce0: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
bcf0: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
bd00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
bd10: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
bd20: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
bd30: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
bd40: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
bd50: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
bd60: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
bd70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bd80: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
bd90: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
bda0: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
bdb0: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
bdc0: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
bdd0: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
bde0: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
bdf0: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
be00: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
be10: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
be20: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
be30: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
be40: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
be50: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
be60: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
be70: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
be80: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
be90: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
bea0: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
beb0: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
bec0: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
bed0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
bee0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
bef0: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
bf00: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
bf10: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
bf20: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bf30: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
bf40: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
bf50: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bf60: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
bf70: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
bf80: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
bf90: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
bfa0: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
bfb0: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
bfc0: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
bfd0: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
bfe0: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
bff0: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
c000: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
c010: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
c020: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
c030: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
c040: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c050: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c060: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c070: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c080: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_GET_HANDLE] o
c090: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
c0a0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a  d to obtain the.
c0b0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61  ** underlying na
c0c0: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
c0d0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
c0e0: 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20   a file handle. 
c0f0: 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f   This file.** co
c100: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
c110: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
c120: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
c130: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
c140: 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73  le and.** writes
c150: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76   the resulting v
c160: 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a  alue there..**.*
c170: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c180: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c190: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
c1a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c1b0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
c1c0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
c1d0: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
c1e0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
c1f0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
c200: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
c210: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
c220: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
c230: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
c240: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
c250: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
c260: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
c270: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
c280: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
c290: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
c2a0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
c2b0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
c2c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c2d0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d  CNTL_WAL_BLOCK]]
c2e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c2f0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c300: 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20   is a signal to 
c310: 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68  the VFS layer th
c320: 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62  at it might.** b
c330: 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74  e advantageous t
c340: 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e  o block on the n
c350: 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20  ext WAL lock if 
c360: 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20  the lock is not 
c370: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61  immediately.** a
c380: 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57  vailable.  The W
c390: 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73  AL subsystem iss
c3a0: 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20  ues this signal 
c3b0: 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63  during rare.** c
c3c0: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20  ircumstances in 
c3d0: 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70  order to fix a p
c3e0: 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f  roblem with prio
c3f0: 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a  rity inversion..
c400: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
c410: 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f  should <em>not</
c420: 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c  em> use this fil
c430: 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a  e-control..**.**
c440: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c450: 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20  NTL_ZIPVFS]].** 
c460: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c470: 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65  L_ZIPVFS] opcode
c480: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c490: 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20  by zipvfs only. 
c4a0: 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53  All other.** VFS
c4b0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c4c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c4d0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  or this opcode..
c4e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c4f0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a  TE_FCNTL_RBU]].*
c500: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c510: 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20  NTL_RBU] opcode 
c520: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c530: 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  y the special VF
c540: 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65  S used by.** the
c550: 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f   RBU extension o
c560: 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  nly.  All other 
c570: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c580: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c590: 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70  D for.** this op
c5a0: 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  code.  .**.** <l
c5b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c5c0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c5d0: 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20  ITE]].** If the 
c5e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
c5f0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
c600: 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73  ] opcode returns
c610: 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e   SQLITE_OK, then
c620: 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73  .** the file des
c630: 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65  criptor is place
c640: 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69 74  d in "batch writ
c650: 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a  e mode", which.*
c660: 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73  * means all subs
c670: 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65  equent write ope
c680: 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20  rations will be 
c690: 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e  deferred and don
c6a0: 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20  e.** atomically 
c6b0: 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c  at the next [SQL
c6c0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c6d0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20  _ATOMIC_WRITE]. 
c6e0: 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74   Systems.** that
c6f0: 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
c700: 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69  batch atomic wri
c710: 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  tes will return 
c720: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e  SQLITE_NOTFOUND.
c730: 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61  .** ^Following a
c740: 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49   successful SQLI
c750: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c760: 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20  TOMIC_WRITE and 
c770: 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20  prior to.** the 
c780: 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  closing [SQLITE_
c790: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c7a0: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a  MIC_WRITE] or.**
c7b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
c7c0: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
c7d0: 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69  RITE], SQLite wi
c7e0: 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46  ll make.** no VF
c7f0: 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  S interface call
c800: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73  s on the same [s
c810: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c  qlite3_file] fil
c820: 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20  e descriptor.** 
c830: 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73  except for calls
c840: 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d   to the xWrite m
c850: 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46  ethod and the xF
c860: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
c870: 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54  d.** with [SQLIT
c880: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
c890: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  T]..**.** <li>[[
c8a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c8b0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
c8c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c8d0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c8e0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63  TOMIC_WRITE] opc
c8f0: 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77  ode causes all w
c900: 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  rite.** operatio
c910: 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65  ns since the pre
c920: 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c  vious successful
c930: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51   call to .** [SQ
c940: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
c950: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74  _ATOMIC_WRITE] t
c960: 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61  o be performed a
c970: 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68  tomically..** Th
c980: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
c990: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
c9a0: 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  OK] if and only 
c9b0: 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77 65  if the writes we
c9c0: 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72  re.** all perfor
c9d0: 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  med successfully
c9e0: 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63   and have been c
c9f0: 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73  ommitted to pers
ca00: 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a  istent storage..
ca10: 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
ca20: 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
ca30: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75   it is successfu
ca40: 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  l, this file con
ca50: 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68  trol takes.** th
ca60: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
ca70: 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77  r out of batch w
ca80: 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61  rite mode so tha
ca90: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
caa0: 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74  .** write operat
cab0: 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e  ions are indepen
cac0: 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  dent..** ^SQLite
cad0: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
cae0: 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ke SQLITE_FCNTL_
caf0: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
cb00: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
cb10: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
cb20: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
cb30: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cb40: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a  OMIC_WRITE]..**.
cb50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cb60: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41  FCNTL_ROLLBACK_A
cb70: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
cb80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
cb90: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
cba0: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
cbb0: 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74   causes all writ
cbc0: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20  e.** operations 
cbd0: 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f  since the previo
cbe0: 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  us successful ca
cbf0: 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54  ll to .** [SQLIT
cc00: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cc10: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62  OMIC_WRITE] to b
cc20: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  e rolled back..*
cc30: 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  * ^This file con
cc40: 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66  trol takes the f
cc50: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f  ile descriptor o
cc60: 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74  ut of batch writ
cc70: 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61  e mode.** so tha
cc80: 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  t all subsequent
cc90: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
cca0: 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e  s are independen
ccb0: 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  t..** ^SQLite wi
ccc0: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
ccd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
cce0: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
ccf0: 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20  TE without.** a 
cd00: 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
cd10: 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45   call to [SQLITE
cd20: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
cd30: 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a  MIC_WRITE]..**.*
cd40: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
cd50: 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55  CNTL_LOCK_TIMEOU
cd60: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
cd70: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49  TE_FCNTL_LOCK_TI
cd80: 4d 45 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61  MEOUT] opcode ca
cd90: 75 73 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f  uses attempts to
cda0: 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c   obtain.** a fil
cdb0: 65 20 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65  e lock using the
cdc0: 20 78 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f   xLock or xShmLo
cdd0: 63 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68  ck methods of th
cde0: 65 20 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a  e VFS to wait.**
cdf0: 20 66 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c   for up to M mil
ce00: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
ce10: 20 66 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20   failing, where 
ce20: 4d 20 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20  M is the single 
ce30: 0a 2a 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  .** unsigned int
ce40: 65 67 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a  eger parameter..
ce50: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
ce60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ce70: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
ce80: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
ce90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cea0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
ceb0: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
cec0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
ced0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
cee0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
cef0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
cf00: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
cf10: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
cf20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
cf30: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
cf40: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
cf50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
cf60: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
cf70: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
cf80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
cf90: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
cfa0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
cfb0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
cfc0: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
cfd0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
cfe0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
cff0: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
d000: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
d010: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
d020: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
d030: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
d040: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
d050: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
d060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d070: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
d080: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
d090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d0a0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
d0b0: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
d0c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d0d0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
d0e0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
d0f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d100: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
d110: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
d120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d130: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
d140: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
d150: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d160: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
d170: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
d180: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d190: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
d1a0: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
d1b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
d1c0: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
d1d0: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
d1e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
d1f0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
d200: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
d210: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
d220: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
d230: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
d240: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d250: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
d260: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
d270: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
d280: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
d290: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
d2a0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
d2b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d2c0: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
d2d0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
d2e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d2f0: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
d300: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
d310: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
d320: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
d330: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
d340: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
d350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d360: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
d370: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a  HANDLE       29.
d380: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d390: 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20  CNTL_PDB        
d3a0: 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 23              30.#
d3b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d3c0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
d3d0: 5f 57 52 49 54 45 20 20 20 20 20 33 31 0a 23 64  _WRITE     31.#d
d3e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d3f0: 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  TL_COMMIT_ATOMIC
d400: 5f 57 52 49 54 45 20 20 20 20 33 32 0a 23 64 65  _WRITE    32.#de
d410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d420: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
d430: 43 5f 57 52 49 54 45 20 20 33 33 0a 23 64 65 66  C_WRITE  33.#def
d440: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d450: 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20  _LOCK_TIMEOUT   
d460: 20 20 20 20 20 20 20 20 33 34 0a 0a 2f 2a 20 64          34../* d
d470: 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20  eprecated names 
d480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d490: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
d4a0: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
d4b0: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
d4c0: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
d4d0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
d4e0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
d4f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
d500: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
d510: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
d520: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
d530: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
d540: 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a  LAST_ERRNO.../*.
d550: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
d560: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
d570: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
d580: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
d590: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
d5a0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
d5b0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
d5c0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
d5d0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
d5e0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
d5f0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
d600: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
d610: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
d620: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
d630: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
d640: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
d650: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
d660: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
d670: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
d680: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
d690: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
d6a0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
d6b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
d6c0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
d6d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d6e0: 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65  F: Loadable Exte
d6f0: 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a  nsion Thunk.**.*
d700: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
d710: 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65  he opaque sqlite
d720: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73  3_api_routines s
d730: 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73  tructure is pass
d740: 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69  ed as.** the thi
d750: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
d760: 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20  entry points of 
d770: 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73  [loadable extens
d780: 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20  ions].  This.** 
d790: 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62  structure must b
d7a0: 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f  e typedefed in o
d7b0: 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f  rder to work aro
d7c0: 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72  und compiler war
d7d0: 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65  nings.** on some
d7e0: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74   platforms..*/.t
d7f0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
d800: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
d810: 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  es sqlite3_api_r
d820: 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20  outines;../*.** 
d830: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
d840: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
d850: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
d860: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
d870: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
d880: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
d890: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
d8a0: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
d8b0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
d8c0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
d8d0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
d8e0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
d8f0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
d900: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
d910: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
d920: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
d930: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
d940: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
d950: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
d960: 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  he VFS interface
d970: 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78   is sometimes ex
d980: 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67  tended by adding
d990: 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74   new methods ont
d9a0: 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45  o.** the end.  E
d9b0: 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e  ach time such an
d9c0: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72   extension occur
d9d0: 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  s, the iVersion 
d9e0: 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72  field.** is incr
d9f0: 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56  emented.  The iV
da00: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61  ersion value sta
da10: 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e  rted out as 1 in
da20: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
da30: 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64  ion 3.5.0] on [d
da40: 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68  ateof:3.5.0], th
da50: 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20  en increased to 
da60: 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65  2.** with SQLite
da70: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d   [version 3.7.0]
da80: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e   on [dateof:3.7.
da90: 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63  0], and then inc
daa0: 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77  reased.** to 3 w
dab0: 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73  ith SQLite [vers
dac0: 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64  ion 3.7.6] on [d
dad0: 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41  ateof:3.7.6].  A
dae0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
daf0: 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e  .** may be appen
db00: 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ded to the sqlit
db10: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e  e3_vfs object an
db20: 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  d the iVersion v
db30: 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72  alue.** may incr
db40: 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75  ease again in fu
db50: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
db60: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65   SQLite..** Note
db70: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
db80: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
db90: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
dba0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
dbb0: 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a  transition from.
dbc0: 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  ** SQLite [versi
dbd0: 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65  on 3.5.9] to [ve
dbe0: 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20  rsion 3.6.0] on 
dbf0: 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a  [dateof:3.6.0].*
dc00: 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  * and yet the iV
dc10: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
dc20: 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a   not modified..*
dc30: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
dc40: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
dc50: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
dc60: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
dc70: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
dc80: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
dc90: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
dca0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
dcb0: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
dcc0: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
dcd0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
dce0: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
dcf0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
dd00: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
dd10: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
dd20: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
dd30: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
dd40: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
dd50: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
dd60: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
dd70: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
dd80: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
dd90: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
dda0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
ddb0: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
ddc0: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
ddd0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
dde0: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
ddf0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
de00: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
de10: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
de20: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
de30: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
de40: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
de50: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
de60: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
de70: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
de80: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
de90: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
dea0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
deb0: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
dec0: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
ded0: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
dee0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
def0: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
df00: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
df10: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
df20: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
df30: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
df40: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
df50: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
df60: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
df70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
df80: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
df90: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
dfa0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
dfb0: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
dfc0: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
dfd0: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
dfe0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
dff0: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
e000: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
e010: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
e020: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
e030: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
e040: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
e050: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
e060: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
e070: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
e080: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
e090: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
e0a0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
e0b0: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
e0c0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
e0d0: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
e0e0: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
e0f0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
e100: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
e110: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
e120: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
e130: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
e140: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
e150: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
e160: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
e170: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
e180: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
e190: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
e1a0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
e1b0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
e1c0: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
e1d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
e1e0: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
e1f0: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
e200: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
e210: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
e220: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
e230: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
e240: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
e250: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
e260: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
e270: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
e280: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
e290: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
e2a0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
e2b0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
e2c0: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
e2d0: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
e2e0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
e2f0: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
e300: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
e310: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
e320: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
e330: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
e340: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
e350: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
e360: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
e370: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
e380: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
e390: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
e3a0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
e3b0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
e3c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
e3d0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
e3e0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
e3f0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
e400: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
e410: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
e420: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
e430: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
e440: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
e450: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
e460: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
e470: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
e480: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
e490: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
e4a0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
e4b0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
e4c0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
e4d0: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
e4e0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
e4f0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
e500: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
e510: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
e520: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
e530: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
e540: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
e550: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e560: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
e570: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e580: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
e590: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e5a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
e5b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e5c0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
e5d0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
e5e0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
e5f0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
e600: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
e610: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
e620: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
e630: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
e640: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e650: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
e660: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
e670: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
e680: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
e690: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
e6a0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
e6b0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
e6c0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
e6d0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
e6e0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
e6f0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
e700: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
e710: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
e720: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
e730: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
e740: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
e750: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
e760: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
e770: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
e780: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
e790: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
e7a0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
e7b0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
e7c0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
e7d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
e7e0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
e7f0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
e800: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
e810: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
e820: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
e830: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
e840: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
e850: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
e860: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
e870: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
e880: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
e890: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
e8a0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
e8b0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
e8c0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
e8d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
e8e0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
e8f0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
e900: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
e910: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
e920: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
e930: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
e940: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
e950: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
e960: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
e970: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
e980: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
e990: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e9a0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
e9b0: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
e9c0: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
e9d0: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
e9e0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
e9f0: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
ea00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
ea10: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
ea20: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
ea30: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
ea40: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
ea50: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
ea60: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
ea70: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
ea80: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
ea90: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
eaa0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
eab0: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
eac0: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
ead0: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
eae0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
eaf0: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
eb00: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
eb10: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
eb20: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
eb30: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
eb40: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
eb50: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
eb60: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
eb70: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
eb80: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
eb90: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
eba0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
ebb0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
ebc0: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
ebd0: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
ebe0: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
ebf0: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
ec00: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
ec10: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
ec20: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
ec30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
ec40: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
ec50: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
ec60: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
ec70: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
ec80: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
ec90: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
eca0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
ecb0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
ecc0: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
ecd0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
ece0: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
ecf0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
ed00: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
ed10: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
ed20: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
ed30: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
ed40: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
ed50: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
ed60: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
ed70: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
ed80: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
ed90: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
eda0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
edb0: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
edc0: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
edd0: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
ede0: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
edf0: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
ee00: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
ee10: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
ee20: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
ee30: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
ee40: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
ee50: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
ee60: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
ee70: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
ee80: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
ee90: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
eea0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
eeb0: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
eec0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
eed0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
eee0: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
eef0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
ef00: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
ef10: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
ef20: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
ef30: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
ef40: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
ef50: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
ef60: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
ef70: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
ef80: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
ef90: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
efa0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
efb0: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
efc0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
efd0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
efe0: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
eff0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
f000: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
f010: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
f020: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
f030: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
f040: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
f050: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
f060: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
f070: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
f080: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
f090: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
f0a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
f0b0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
f0c0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
f0d0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
f0e0: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
f0f0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
f100: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
f110: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
f120: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
f130: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
f140: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f150: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
f160: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
f170: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
f180: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
f190: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
f1a0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
f1b0: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
f1c0: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
f1d0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
f1e0: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
f1f0: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
f200: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
f210: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
f220: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
f230: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
f240: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
f250: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
f260: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
f270: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
f280: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
f290: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
f2a0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
f2b0: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
f2c0: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
f2d0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
f2e0: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
f2f0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
f300: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
f310: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
f320: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
f330: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
f340: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
f350: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
f360: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
f370: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
f380: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
f390: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
f3a0: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
f3b0: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
f3c0: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
f3d0: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
f3e0: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
f3f0: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
f400: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
f410: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
f420: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
f430: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
f440: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
f450: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
f460: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
f470: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
f480: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
f490: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
f4a0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
f4b0: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
f4c0: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
f4d0: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
f4e0: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
f4f0: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
f500: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
f510: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
f520: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
f530: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
f540: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
f550: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
f560: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
f570: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
f580: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
f590: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
f5a0: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
f5b0: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
f5c0: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
f5d0: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
f5e0: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
f5f0: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
f600: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
f610: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
f620: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
f630: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
f640: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
f650: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
f660: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
f670: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
f680: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
f690: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
f6a0: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
f6b0: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
f6c0: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
f6d0: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
f6e0: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
f6f0: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
f700: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
f710: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
f720: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
f730: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
f740: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
f750: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
f760: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
f770: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
f780: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
f790: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
f7a0: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
f7b0: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
f7c0: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
f7d0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
f7e0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
f7f0: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
f800: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
f810: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
f820: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
f830: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
f840: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
f850: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
f860: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
f870: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
f880: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
f890: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
f8a0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
f8b0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
f8c0: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
f8d0: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
f8e0: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
f8f0: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
f900: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
f910: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
f920: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
f930: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
f940: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
f950: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
f960: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
f970: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
f980: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
f990: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
f9a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
f9b0: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
f9c0: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
f9d0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
f9e0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
f9f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
fa00: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
fa10: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
fa20: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
fa30: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
fa40: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
fa50: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
fa60: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
fa70: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
fa80: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
fa90: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
faa0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
fab0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
fac0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
fad0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
fae0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
faf0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
fb00: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
fb10: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
fb20: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
fb30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
fb40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
fb50: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
fb60: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
fb70: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
fb80: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
fb90: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
fba0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
fbb0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
fbc0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
fbd0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
fbe0: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
fbf0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
fc00: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
fc10: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
fc20: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
fc30: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
fc40: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
fc50: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
fc60: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
fc70: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
fc80: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
fc90: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
fca0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
fcb0: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
fcc0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
fcd0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
fce0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
fcf0: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
fd00: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
fd10: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
fd20: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
fd30: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
fd40: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
fd50: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
fd60: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
fd70: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
fd80: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
fd90: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
fda0: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
fdb0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
fdc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fdd0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
fde0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
fdf0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
fe00: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
fe10: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
fe20: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
fe30: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
fe40: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
fe50: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
fe60: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
fe70: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
fe80: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
fe90: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
fea0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
feb0: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
fec0: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
fed0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
fee0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
fef0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
ff00: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
ff10: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
ff20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
ff30: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
ff40: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
ff50: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
ff60: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
ff70: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
ff80: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
ff90: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
ffa0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
ffb0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
ffc0: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
ffd0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
ffe0: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
fff0: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
10000 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
10010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
10020 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
10030 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
10040 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
10050 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
10060 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
10070 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
10080 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
10090 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
100a0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
100b0 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
100c0 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
100d0 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
100e0 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
100f0 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
10100 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
10110 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
10120 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
10130 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
10140 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
10150 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
10160 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
10170 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
10180 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10190 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
101a0 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
101b0 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
101c0 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
101d0 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
101e0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
101f0 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
10200 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
10210 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
10220 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
10230 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
10240 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10250 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
10260 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
10270 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
10280 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
10290 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
102a0 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
102b0 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
102c0 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
102d0 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
102e0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
102f0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10300 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
10310 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
10320 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
10330 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10340 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
10350 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
10360 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
10370 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
10380 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
10390 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
103a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
103b0 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
103c0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
103d0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
103e0 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
103f0 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
10400 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
10410 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10420 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
10430 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
10440 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10450 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
10460 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
10470 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
10480 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
10490 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
104a0 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
104b0 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
104c0 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
104d0 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
104e0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
104f0 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
10500 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
10510 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
10520 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
10530 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
10540 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
10550 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
10560 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
10570 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10580 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10590 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
105a0 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
105b0 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
105c0 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
105d0 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
105e0 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
105f0 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
10600 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10610 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
10620 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
10630 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
10640 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
10650 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
10660 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
10670 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72  given on the cor
10680 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
10690 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
106a0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
106b0 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
106c0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
106d0 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
106e0 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
106f0 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
10700 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
10710 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
10720 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
10730 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
10740 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
10750 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
10760 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
10770 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
10780 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
10790 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
107a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
107b0 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
107c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
107d0 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
107e0 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
107f0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
10800 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
10810 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
10820 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
10830 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
10840 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
10850 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
10860 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
10870 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
10880 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
10890 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
108a0 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
108b0 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
108c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
108d0 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
108e0 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
108f0 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
10900 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
10910 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
10920 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10930 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
10940 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
10950 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
10960 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
10970 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
10980 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
10990 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
109a0 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
109b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
109c0 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
109d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
109e0 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
109f0 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
10a00 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
10a10 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
10a20 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
10a30 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
10a40 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
10a50 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
10a60 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
10a70 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
10a80 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
10a90 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
10aa0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
10ab0 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
10ac0 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
10ad0 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
10ae0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
10af0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10b00 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
10b10 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
10b20 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
10b30 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
10b40 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
10b50 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10b60 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
10b70 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
10b80 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10b90 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
10ba0 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
10bb0 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
10bc0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
10bd0 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
10be0 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
10bf0 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
10c00 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
10c10 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
10c20 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10c30 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
10c40 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
10c50 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
10c60 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
10c70 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
10c80 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
10c90 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
10ca0 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
10cb0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
10cc0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10cd0 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
10ce0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
10cf0 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
10d00 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
10d10 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
10d20 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
10d30 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
10d40 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10d50 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
10d60 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
10d70 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10d80 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
10d90 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
10da0 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
10db0 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
10dc0 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
10dd0 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
10de0 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
10df0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
10e00 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
10e10 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
10e20 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
10e30 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
10e40 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
10e50 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
10e60 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
10e70 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
10e80 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
10e90 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
10ea0 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
10eb0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
10ec0 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
10ed0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
10ee0 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
10ef0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
10f00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
10f10 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10f20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10f30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
10f40 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
10f50 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
10f60 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10f70 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
10f80 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
10f90 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
10fa0 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
10fb0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
10fc0 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
10fd0 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
10fe0 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
10ff0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
11000 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
11010 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
11020 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11030 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
11040 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
11050 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
11060 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
11070 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
11080 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
11090 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
110a0 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
110b0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
110c0 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
110d0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
110e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
110f0 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
11100 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
11110 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
11120 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
11130 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
11140 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
11150 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
11160 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
11170 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
11180 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
11190 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
111a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
111b0 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
111c0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
111d0 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
111e0 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
111f0 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
11200 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
11210 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
11220 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
11230 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
11240 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
11250 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
11260 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
11270 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
11280 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
11290 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
112a0 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
112b0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
112c0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
112d0 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
112e0 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
112f0 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
11300 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
11310 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
11320 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
11330 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
11340 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
11350 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
11360 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11370 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
11380 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
11390 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
113a0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
113b0 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
113c0 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
113d0 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
113e0 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
113f0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
11400 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
11410 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11420 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
11430 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
11440 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
11450 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
11460 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11470 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11480 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
11490 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
114a0 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
114b0 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
114c0 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
114d0 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
114e0 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
114f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
11500 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
11510 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
11520 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
11530 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
11540 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
11550 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
11560 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
11570 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
11580 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
11590 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
115a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
115b0 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
115c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
115d0 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
115e0 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
115f0 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
11600 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11610 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
11620 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
11630 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
11640 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
11650 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
11660 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
11670 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11680 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
11690 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
116a0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
116b0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
116c0 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
116d0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
116e0 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
116f0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
11700 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
11710 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
11720 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11730 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
11740 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
11750 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
11760 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
11770 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
11780 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
11790 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
117a0 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
117b0 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
117c0 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
117d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
117e0 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
117f0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
11800 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
11810 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
11820 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
11830 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
11840 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
11850 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
11860 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
11870 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
11880 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
11890 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
118a0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
118b0 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
118c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
118d0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
118e0 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
118f0 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
11900 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
11910 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
11920 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
11930 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11940 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
11950 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
11960 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
11970 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
11980 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11990 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
119a0 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
119b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
119c0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
119d0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
119e0 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
119f0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
11a00 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
11a10 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
11a20 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
11a30 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
11a40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
11a50 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
11a60 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
11a70 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
11a80 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
11a90 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
11aa0 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
11ab0 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
11ac0 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
11ad0 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
11ae0 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
11af0 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
11b00 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54  eeds..**.** <b>T
11b10 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
11b20 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
11b30 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
11b40 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
11b50 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
11b60 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
11b70 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
11b80 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
11b90 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
11ba0 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
11bb0 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
11bc0 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  g.</b>.**.** The
11bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11be0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d  ) interface.** m
11bf0 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
11c00 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
11c10 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
11c20 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
11c30 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11c40 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
11c50 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
11c60 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
11c70 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
11c80 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
11c90 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
11ca0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
11cb0 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
11cc0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11cd0 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
11ce0 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
11cf0 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
11d00 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
11d10 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
11d20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
11d30 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
11d40 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
11d50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
11d60 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
11d70 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
11d80 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
11d90 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
11da0 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
11db0 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
11dc0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
11dd0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
11de0 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
11df0 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
11e00 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
11e10 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
11e20 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
11e30 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
11e40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11e50 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
11e60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
11e70 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
11e80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11e90 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
11ea0 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
11eb0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
11ec0 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
11ed0 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
11ee0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
11ef0 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
11f00 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
11f10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
11f20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
11f30 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
11f40 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
11f50 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
11f60 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11f70 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
11f80 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  nnections.** MET
11f90 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
11fa0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
11fb0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
11fc0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
11fd0 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
11fe0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
11ff0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
12000 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
12010 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
12020 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
12030 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
12040 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
12050 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
12060 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
12070 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12080 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
12090 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
120a0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
120b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
120c0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
120d0 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
120e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
120f0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
12100 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
12110 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
12120 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
12130 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
12140 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
12150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12160 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
12170 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
12180 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
12190 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
121a0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
121b0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
121c0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
121d0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
121e0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
121f0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
12200 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
12210 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
12220 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
12230 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
12240 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
12250 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
12260 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
12270 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
12280 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
12290 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
122a0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
122b0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
122c0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
122d0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
122e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
122f0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
12300 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
12310 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
12320 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
12330 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
12340 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12350 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
12360 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
12370 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
12380 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12390 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
123a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
123b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
123c0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
123d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
123e0 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
123f0 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
12400 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12410 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
12420 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
12430 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
12440 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12450 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
12460 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
12470 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
12480 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
12490 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
124a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
124b0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
124c0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
124d0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
124e0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
124f0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
12500 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
12510 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
12520 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
12530 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
12540 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
12550 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
12560 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
12570 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
12580 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
12590 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
125a0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
125b0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
125c0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
125d0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
125e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
125f0 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
12600 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
12610 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
12620 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
12630 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
12640 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
12650 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
12660 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
12670 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
12680 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
12690 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
126a0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
126b0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
126c0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
126d0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
126e0 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
126f0 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
12700 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
12710 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
12720 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
12730 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
12740 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
12750 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
12760 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
12770 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
12780 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
12790 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
127a0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
127b0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
127c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
127d0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
127e0 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
127f0 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
12800 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
12810 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
12820 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
12830 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
12840 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
12850 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
12860 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
12870 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
12880 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
12890 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
128a0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
128b0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
128c0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
128d0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
128e0 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
128f0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
12900 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
12910 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
12920 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
12930 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
12940 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
12950 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
12960 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12970 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
12980 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
12990 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
129a0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
129b0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
129c0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
129d0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
129e0 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
129f0 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
12a00 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
12a10 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
12a20 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
12a30 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
12a40 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
12a50 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
12a60 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
12a70 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
12a80 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
12a90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12aa0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
12ab0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
12ac0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
12ad0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
12ae0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
12af0 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
12b00 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
12b10 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
12b20 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
12b30 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
12b40 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
12b50 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
12b60 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
12b70 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
12b80 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
12b90 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
12ba0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
12bb0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
12bc0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
12bd0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
12be0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
12bf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
12c00 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
12c10 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
12c20 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
12c30 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
12c40 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
12c50 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
12c60 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
12c70 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
12c80 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
12c90 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
12ca0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
12cb0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
12cc0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
12cd0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12ce0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
12cf0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
12d00 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
12d10 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
12d20 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
12d30 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
12d40 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
12d50 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
12d60 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
12d70 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12d80 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
12d90 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
12da0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
12db0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
12dc0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
12dd0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
12de0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
12df0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
12e00 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
12e10 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12e20 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
12e30 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
12e40 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
12e50 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
12e60 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
12e70 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
12e80 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
12e90 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
12ea0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
12eb0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
12ec0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
12ed0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
12ee0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
12ef0 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
12f00 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
12f10 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12f20 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
12f30 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
12f40 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12f50 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
12f60 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
12f70 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
12f80 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
12f90 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
12fa0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
12fb0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
12fc0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
12fd0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
12fe0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
12ff0 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
13000 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
13010 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
13020 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
13030 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
13040 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
13050 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
13060 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
13070 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
13080 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
13090 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
130a0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
130b0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
130c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
130d0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
130e0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
130f0 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
13100 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
13110 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
13120 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
13130 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
13140 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
13150 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
13160 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
13170 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
13180 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
13190 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
131a0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
131b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
131c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
131d0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
131e0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
131f0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
13200 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
13210 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
13220 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
13230 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13240 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
13250 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
13260 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
13270 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
13280 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
13290 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
132a0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
132b0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
132c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
132d0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
132e0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
132f0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
13300 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
13310 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
13320 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13330 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
13340 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
13350 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
13360 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13370 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
13380 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
13390 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
133a0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
133b0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
133c0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
133d0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
133e0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
133f0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
13400 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
13410 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
13420 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13430 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
13440 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
13450 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
13460 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
13470 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13480 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13490 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
134a0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
134b0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
134c0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
134d0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
134e0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
134f0 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
13500 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
13510 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
13520 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13530 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13540 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13550 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13560 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13570 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13580 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13590 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
135a0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
135b0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
135c0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
135d0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
135e0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
135f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13600 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
13610 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13620 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
13630 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13640 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
13650 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13660 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
13670 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13680 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
13690 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
136a0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
136b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
136c0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
136d0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
136e0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
136f0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
13700 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
13710 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
13720 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
13730 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
13740 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
13750 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
13760 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
13770 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
13780 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
13790 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
137a0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
137b0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
137c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
137d0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
137e0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
137f0 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
13800 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
13810 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
13820 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
13830 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
13840 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
13850 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
13860 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
13870 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
13880 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
13890 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
138a0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
138b0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
138c0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
138d0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
138e0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
138f0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13900 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13910 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
13920 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
13930 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
13940 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
13950 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
13960 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13970 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
13980 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13990 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
139a0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
139b0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
139c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
139d0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
139e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
139f0 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
13a00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13a10 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
13a20 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
13a30 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
13a40 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
13a50 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
13a60 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
13a70 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
13a80 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
13a90 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
13aa0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
13ab0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
13ac0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
13ad0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
13ae0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13af0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
13b00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
13b10 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
13b20 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
13b30 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
13b40 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
13b50 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
13b60 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13b70 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
13b80 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
13b90 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
13ba0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
13bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13bc0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
13bd0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
13be0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
13bf0 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
13c00 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
13c10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13c20 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
13c30 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
13c40 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
13c50 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
13c60 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
13c70 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
13c80 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13c90 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13ca0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13cb0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13cc0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13cd0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
13ce0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
13cf0 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
13d00 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
13d10 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
13d20 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13d30 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
13d40 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
13d50 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
13d60 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
13d70 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
13d80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
13d90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13da0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13db0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
13dc0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
13dd0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13de0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13df0 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
13e00 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13e10 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
13e20 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
13e30 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13e40 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
13e50 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
13e60 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
13e70 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
13e80 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
13e90 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
13ea0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
13eb0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
13ec0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
13ed0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13ee0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
13ef0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
13f00 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
13f10 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
13f20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
13f30 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
13f40 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13f50 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
13f60 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
13f70 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
13f80 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
13f90 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13fa0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
13fb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13fc0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
13fd0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
13fe0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13ff0 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
14000 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14010 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14020 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14030 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14040 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
14050 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
14060 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
14070 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
14080 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
14090 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
140a0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
140b0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
140c0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
140d0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
140e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
140f0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
14100 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
14110 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
14120 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
14130 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
14140 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14150 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
14160 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
14170 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
14180 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
14190 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
141a0 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  SMALL_MALLOC]] <
141b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
141c0 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64  _SMALL_MALLOC</d
141d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
141e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
141f0 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  ALL_MALLOC optio
14200 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
14210 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79  rgument of.** ty
14220 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
14230 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
14240 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65 20  , which if true 
14250 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20  provides a hint 
14260 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61  to.** SQLite tha
14270 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69  t it should avoi
14280 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61  d large memory a
14290 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f  llocations if po
142a0 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74  ssible..** SQLit
142b0 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65  e will run faste
142c0 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65 20  r if it is free 
142d0 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65  to make large me
142e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
142f0 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70  ,.** but some ap
14300 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
14310 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c  prefer to run sl
14320 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65  ower in exchange
14330 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65   for.** guarante
14340 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20  es about memory 
14350 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68  fragmentation th
14360 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20  at are possible 
14370 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f  if large.** allo
14380 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69  cations are avoi
14390 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ded.  This hint 
143a0 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e  is normally off.
143b0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
143c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
143d0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
143e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
143f0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
14400 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
14410 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14420 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
14430 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
14440 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
14450 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14460 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
14470 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
14480 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
14490 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
144a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
144b0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
144c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
144d0 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
144e0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
144f0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
14500 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
14510 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
14520 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
14530 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
14540 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
14550 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14560 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
14570 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
14580 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
14590 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
145a0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
145b0 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
145c0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
145d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
145e0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
145f0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
14600 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
14610 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
14620 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
14630 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
14640 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
14650 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
14660 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
14670 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
14680 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
14690 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
146a0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
146b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
146c0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
146d0 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
146e0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
146f0 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  H option is no l
14700 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c  onger used..** <
14710 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14720 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14730 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
14740 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14750 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
14760 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14770 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
14780 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
14790 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
147a0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
147b0 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
147c0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
147d0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
147e0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
147f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
14800 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
14810 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
14820 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
14830 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14840 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
14850 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
14860 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
14870 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
14880 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
14890 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
148a0 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
148b0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
148c0 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
148d0 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
148e0 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
148f0 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
14900 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
14910 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
14920 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
14930 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
14940 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
14950 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
14960 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
14970 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
14980 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
14990 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
149a0 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
149b0 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
149c0 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
149d0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
149e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
149f0 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
14a00 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
14a10 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
14a20 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
14a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14a40 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
14a50 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
14a60 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
14a70 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
14a80 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
14a90 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
14aa0 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
14ab0 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
14ac0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
14ad0 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
14ae0 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
14af0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
14b00 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
14b10 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
14b20 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
14b30 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
14b40 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
14b50 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
14b60 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
14b70 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
14b80 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
14b90 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
14ba0 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
14bb0 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
14bc0 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
14bd0 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
14be0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
14bf0 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
14c00 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
14c10 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
14c20 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
14c30 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
14c40 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
14c50 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
14c60 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
14c70 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
14c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14c90 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
14ca0 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
14cb0 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
14cc0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
14cd0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
14ce0 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
14cf0 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
14d00 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
14d10 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
14d20 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
14d30 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
14d40 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
14d50 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
14d60 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
14d70 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
14d80 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
14d90 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
14da0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
14db0 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
14dc0 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
14dd0 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
14de0 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
14df0 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
14e00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14e10 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
14e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14e30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
14e40 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14e50 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
14e60 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
14e70 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
14e80 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
14e90 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
14ea0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
14eb0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14ec0 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
14ed0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
14ee0 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
14ef0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
14f00 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
14f10 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
14f20 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
14f30 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
14f40 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
14f50 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  th either [SQLIT
14f60 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
14f70 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ] or [SQLITE_ENA
14f80 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64  BLE_MEMSYS5] and
14f90 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
14fa0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e  ITE_ERROR] if in
14fb0 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e  voked otherwise.
14fc0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
14fd0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
14fe0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
14ff0 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
15000 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
15010 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
15020 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
15030 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
15040 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
15050 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
15060 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
15070 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
15080 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
15090 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
150a0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
150b0 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
150c0 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
150d0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
150e0 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
150f0 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
15100 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
15110 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
15120 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
15130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
15140 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
15150 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
15160 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
15170 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
15180 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
15190 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
151a0 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
151b0 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
151c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
151d0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
151e0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
151f0 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
15200 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
15210 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
15220 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
15230 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
15240 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
15250 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
15260 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
15270 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
15280 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
15290 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
152a0 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
152b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
152c0 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
152d0 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
152e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
152f0 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
15300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15310 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
15320 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
15330 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e  FIG_MUTEX option
15340 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15350 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
15360 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
15370 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
15380 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
15390 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
153a0 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
153b0 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
153c0 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  s alternative lo
153d0 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
153e0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
153f0 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68  d.** in place th
15400 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
15410 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
15420 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
15430 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  akes a copy of.*
15440 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
15450 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
15460 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
15470 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
15480 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
15490 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
154a0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
154b0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
154c0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
154d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
154e0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
154f0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
15500 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
15510 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
15520 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
15530 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
15540 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
15550 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
15560 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15570 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
15580 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
15590 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
155a0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
155b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
155c0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
155d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
155e0 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
155f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15600 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
15610 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
15620 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f  ONFIG_GETMUTEX o
15630 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15640 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
15650 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
15660 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
15670 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
15680 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15690 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
156a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
156b0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
156c0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
156d0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
156e0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
156f0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
15700 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
15710 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
15720 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
15730 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
15740 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
15750 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
15760 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
15770 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
15780 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
15790 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
157a0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
157b0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
157c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
157d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
157e0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
157f0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
15800 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15810 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
15820 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
15830 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
15840 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
15850 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
15860 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
15870 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
15880 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
15890 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
158a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
158b0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
158c0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
158d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
158e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
158f0 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
15900 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15910 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
15920 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
15930 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70  FIG_LOOKASIDE op
15940 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
15950 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
15960 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64  termine.** the d
15970 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c  efault size of l
15980 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
15990 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73  on each [databas
159a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
159b0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
159c0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
159d0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
159e0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
159f0 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
15a00 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
15a10 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
15a20 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
15a30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15a40 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f  .)^  ^(SQLITE_CO
15a50 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a  NFIG_LOOKASIDE.*
15a60 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65  * sets the <i>de
15a70 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
15a80 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
15a90 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15aa0 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74  OOKASIDE].** opt
15ab0 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ion to [sqlite3_
15ac0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
15ad0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
15ae0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
15af0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
15b00 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
15b10 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
15b20 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15b30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15b40 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
15b50 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
15b60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
15b70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15b80 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
15b90 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
15ba0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
15bb0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
15bc0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
15bd0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
15be0 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
15bf0 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ct specifies.** 
15c00 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  the interface to
15c10 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
15c20 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
15c30 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74  ion.)^.** ^SQLit
15c40 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
15c50 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
15c60 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
15c70 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
15c80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15c90 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
15ca0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15cb0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
15cc0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
15cd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15ce0 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  TPCACHE2 option 
15cf0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15d00 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
15d10 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
15d20 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
15d30 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
15d40 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
15d50 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63  pies of.** the c
15d60 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68  urrent page cach
15d70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
15d80 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
15d90 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
15da0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15db0 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
15dc0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
15dd0 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
15de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15df0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
15e00 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
15e10 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
15e20 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
15e30 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
15e40 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
15e50 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
15e60 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
15e70 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
15e80 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
15e90 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
15ea0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
15eb0 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
15ec0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
15ed0 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
15ee0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
15ef0 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
15f00 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
15f10 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
15f20 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
15f30 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
15f40 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
15f50 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
15f60 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
15f70 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
15f80 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
15f90 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
15fa0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
15fb0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
15fc0 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
15fd0 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
15fe0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
15ff0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16000 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
16010 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
16020 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
16030 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
16040 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
16050 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
16060 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
16070 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
16080 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
16090 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
160a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
160b0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
160c0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
160d0 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
160e0 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
160f0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
16100 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
16110 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
16120 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16130 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
16140 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
16150 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
16160 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
16170 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
16180 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
16190 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
161a0 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
161b0 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
161c0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
161d0 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
161e0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
161f0 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
16200 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
16210 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
16220 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
16230 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
16240 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
16250 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
16260 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
16270 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
16280 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16290 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
162a0 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
162b0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
162c0 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74  FIG_URI option t
162d0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
162e0 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
162f0 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65  nt..** If non-ze
16300 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
16310 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
16320 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
16330 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
16340 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49  ero,.** then URI
16350 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
16360 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
16370 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
16380 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
16390 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  * enabled, all f
163a0 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20  ilenames passed 
163b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
163c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
163d0 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  en_v2()],.** [sq
163e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
163f0 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
16400 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
16410 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
16420 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
16430 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
16440 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
16450 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
16460 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
16470 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
16480 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
16490 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
164a0 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
164b0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
164c0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
164d0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
164e0 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
164f0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
16500 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
16510 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
16520 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
16530 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
16540 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
16550 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
16560 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
16570 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
16580 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
16590 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
165a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
165b0 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
165c0 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
165d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
165e0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
165f0 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
16600 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
16610 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
16620 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16630 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16640 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20  DEX_SCAN option 
16650 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
16660 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65  nteger.** argume
16670 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
16680 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
16690 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
166a0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
166b0 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  le.** the use of
166c0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
166d0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
166e0 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
166f0 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a  ery optimizer..*
16700 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
16710 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
16720 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
16730 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
16740 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16750 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16760 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
16770 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
16780 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
16790 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
167a0 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
167b0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
167c0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
167d0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
167e0 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
167f0 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
16800 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
16810 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
16820 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
16830 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
16840 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
16850 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
16860 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
16870 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
16880 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
16890 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
168a0 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
168b0 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
168c0 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
168d0 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
168e0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
168f0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
16900 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16910 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
16920 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
16930 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16940 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
16950 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16960 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
16970 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
16980 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
16990 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
169a0 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
169b0 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
169c0 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
169d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
169e0 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
169f0 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
16a00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16a10 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
16a20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16a30 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
16a40 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
16a50 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
16a60 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
16a70 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
16a80 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
16a90 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
16aa0 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
16ab0 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
16ac0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
16ad0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
16ae0 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
16af0 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
16b00 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
16b10 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
16b20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
16b30 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
16b40 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
16b50 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
16b60 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
16b70 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
16b80 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
16b90 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
16ba0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
16bb0 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
16bc0 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
16bd0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
16be0 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
16bf0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
16c00 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
16c10 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
16c20 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
16c30 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
16c40 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
16c50 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
16c60 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
16c70 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
16c80 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
16c90 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
16ca0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
16cb0 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
16cc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
16cd0 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
16ce0 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
16cf0 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
16d00 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
16d10 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
16d20 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
16d30 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
16d40 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
16d50 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
16d60 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
16d70 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
16d80 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
16d90 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
16da0 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
16db0 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
16dc0 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
16dd0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16de0 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
16df0 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
16e00 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
16e10 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
16e20 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
16e30 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
16e40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16e50 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
16e60 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16e70 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
16e80 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
16e90 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
16ea0 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
16eb0 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
16ec0 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
16ed0 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
16ee0 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
16ef0 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
16f00 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
16f10 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
16f20 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
16f30 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
16f40 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
16f50 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
16f60 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
16f70 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
16f80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16f90 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
16fa0 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
16fb0 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
16fc0 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
16fd0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16fe0 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
16ff0 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
17000 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
17010 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
17020 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e  ** will be silen
17030 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66  tly truncated if
17040 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68   necessary so th
17050 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  at it does not e
17060 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  xceed the.** com
17070 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
17080 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
17090 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
170a0 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
170b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
170c0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
170d0 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
170e0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
170f0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
17100 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
17110 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
17120 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
17130 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
17140 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
17150 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
17160 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17170 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17180 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  IZE.** <dd>^The 
17190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
171a0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74  N32_HEAPSIZE opt
171b0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
171c0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
171d0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66  is.** compiled f
171e0 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20  or Windows with 
171f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
17200 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
17210 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
17220 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54   defined. ^SQLIT
17230 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17240 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
17250 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
17260 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
17270 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
17280 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
17290 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
172a0 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  heap..**.** [[SQ
172b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
172c0 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64  HE_HDRSZ]].** <d
172d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
172e0 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20  PCACHE_HDRSZ.** 
172f0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17300 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17310 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  RSZ option takes
17320 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
17330 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
17340 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
17350 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74  integer and writ
17360 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  es into that int
17370 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20  eger the number 
17380 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65  of extra.** byte
17390 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69  s per page requi
173a0 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67  red for each pag
173b0 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e in [SQLITE_CON
173c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
173d0 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** The amount of
173e0 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71   extra space req
173f0 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65  uired can change
17400 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
17410 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74  e compiler,.** t
17420 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20  arget platform, 
17430 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
17440 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
17450 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d  TE_CONFIG_PMASZ]
17460 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17470 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20  CONFIG_PMASZ.** 
17480 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17490 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74  CONFIG_PMASZ opt
174a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
174b0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
174c0 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69  ch.** is an unsi
174d0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
174e0 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d   sets the "Minim
174f0 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72  um PMA Size" for
17500 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64   the multithread
17510 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20  ed.** sorter to 
17520 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54  that integer.  T
17530 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d  he default minim
17540 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73  um PMA Size is s
17550 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
17560 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53  LITE_SORTER_PMAS
17570 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  Z] compile-time 
17580 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72  option.  New thr
17590 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65  eads are launche
175a0 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74  d.** to help wit
175b0 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e  h sort operation
175c0 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65  s when multithre
175d0 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20  aded sorting.** 
175e0 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e  is enabled (usin
175f0 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68  g the [PRAGMA th
17600 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20  reads] command) 
17610 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  and the amount o
17620 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20  f content.** to 
17630 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64  be sorted exceed
17640 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20  s the page size 
17650 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75  times the minimu
17660 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41  m of the.** [PRA
17670 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20  GMA cache_size] 
17680 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73  setting and this
17690 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   value..**.** [[
176a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
176b0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a  MTJRNL_SPILL]].*
176c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
176d0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
176e0 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  LL.** <dd>^The S
176f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
17700 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69  TJRNL_SPILL opti
17710 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17720 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
17730 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65  h.** becomes the
17740 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [statement jour
17750 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69  nal] spill-to-di
17760 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a  sk threshold.  .
17770 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f  ** [Statement jo
17780 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64  urnals] are held
17790 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c   in memory until
177a0 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20   their size (in 
177b0 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64  bytes).** exceed
177c0 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64  s this threshold
177d0 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74  , at which point
177e0 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65   they are writte
177f0 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72  n to disk..** Or
17800 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c   if the threshol
17810 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65  d is -1, stateme
17820 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20  nt journals are 
17830 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65  always held.** e
17840 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65  xclusively in me
17850 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d  mory..** Since m
17860 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  any statement jo
17870 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63  urnals never bec
17880 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69  ome large, setti
17890 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20  ng the spill.** 
178a0 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76  threshold to a v
178b0 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b  alue such as 64K
178c0 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72  iB can greatly r
178d0 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74  educe the amount
178e0 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69   of.** I/O requi
178f0 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73  red to support s
17900 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63  tatement rollbac
17910 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  k..** The defaul
17920 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73  t value for this
17930 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74   setting is cont
17940 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  rolled by the.**
17950 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e   [SQLITE_STMTJRN
17960 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65  L_SPILL] compile
17970 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
17980 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17990 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49  FIG_SORTERREF_SI
179a0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
179b0 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52  TE_CONFIG_SORTER
179c0 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  REF_SIZE.** <dd>
179d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
179e0 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45  G_SORTERREF_SIZE
179f0 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20   option accepts 
17a00 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
17a10 65 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 69  er.** of type (i
17a20 6e 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76 61  nt) - the new va
17a30 6c 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74 65  lue of the sorte
17a40 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65  r-reference size
17a50 20 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55   threshold..** U
17a60 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c  sually, when SQL
17a70 69 74 65 20 75 73 65 73 20 61 6e 20 65 78 74 65  ite uses an exte
17a80 72 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64  rnal sort to ord
17a90 65 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f 72  er records accor
17aa0 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52  ding.** to an OR
17ab0 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20 61  DER BY clause, a
17ac0 6c 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69 72  ll fields requir
17ad0 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ed by the caller
17ae0 20 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20   are present in 
17af0 74 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65  the.** sorted re
17b00 63 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c 20  cords. However, 
17b10 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  if SQLite determ
17b20 69 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74 68  ines based on th
17b30 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 0a  e declared type.
17b40 2a 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63 6f  ** of a table co
17b50 6c 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76 61  lumn that its va
17b60 6c 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 20  lues are likely 
17b70 74 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67 65  to be very large
17b80 20 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61   - larger.** tha
17b90 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 64  n the configured
17ba0 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63   sorter-referenc
17bb0 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64  e size threshold
17bc0 20 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72 65   - then a refere
17bd0 6e 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64  nce.** is stored
17be0 20 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64 20   in each sorted 
17bf0 72 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20 72  record and the r
17c00 65 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76  equired column v
17c10 61 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20  alues loaded.** 
17c20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73  from the databas
17c30 65 20 61 73 20 72 65 63 6f 72 64 73 20 61 72 65  e as records are
17c40 20 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f 72   returned in sor
17c50 74 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20 64  ted order. The d
17c60 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
17c70 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  for this option 
17c80 69 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65 20  is to never use 
17c90 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f  this optimizatio
17ca0 6e 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61 20  n. Specifying a 
17cb0 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61 6c  .** negative val
17cc0 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69  ue for this opti
17cd0 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65 20  on restores the 
17ce0 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 75  default behaviou
17cf0 72 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  r..** This optio
17d00 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
17d10 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
17d20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
17d30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
17d40 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 45  ABLE_SORTER_REFE
17d50 52 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d  RENCES] compile-
17d60 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
17d70 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
17d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17d90 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
17da0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
17db0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17dc0 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
17dd0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
17de0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17df0 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
17e00 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
17e10 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17e20 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
17e30 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
17e40 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
17e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17e60 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
17e70 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
17e80 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
17e90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17ea0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
17eb0 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e      6  /* No lon
17ec0 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
17ed0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17ee0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
17ef0 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
17f00 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
17f10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17f20 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
17f30 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
17f40 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
17f50 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
17f60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
17f70 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
17f80 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
17f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17fa0 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
17fb0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
17fc0 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
17fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17fe0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
17ff0 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
18000 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
18010 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
18020 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
18030 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
18040 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
18050 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
18060 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
18070 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
18080 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
18090 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
180a0 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
180b0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
180c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
180d0 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
180e0 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
180f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18100 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
18110 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
18120 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
18130 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18140 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
18150 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
18160 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18170 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
18180 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
18190 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
181a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
181b0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
181c0 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
181d0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
181e0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
181f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
18200 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
18210 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
18220 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18230 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
18240 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
18250 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
18260 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18270 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
18280 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
18290 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
182a0 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
182b0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
182c0 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
182d0 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
182e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
182f0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
18300 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20  HDRSZ        24 
18310 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a   /* int *psz */.
18320 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18330 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20  ONFIG_PMASZ     
18340 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a            25  /*
18350 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a   unsigned int sz
18360 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  Pma */.#define S
18370 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
18380 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20  TJRNL_SPILL     
18390 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   26  /* int nByt
183a0 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
183b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
183c0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32  _MALLOC        2
183d0 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  7  /* boolean */
183e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
183f0 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46  CONFIG_SORTERREF
18400 5f 53 49 5a 45 20 20 20 20 20 20 32 38 20 20 2f  _SIZE      28  /
18410 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a  * int nByte */..
18420 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18430 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
18440 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
18450 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
18460 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
18470 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
18480 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
18490 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
184a0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
184b0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
184c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
184d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
184e0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
184f0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
18500 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
18510 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
18520 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
18530 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
18540 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
18550 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
18560 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
18570 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
18580 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
18590 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
185a0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
185b0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
185c0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
185d0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
185e0 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
185f0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
18600 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
18610 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
18620 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
18630 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
18640 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
18650 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
18660 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
18670 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
18680 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
18690 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
186a0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
186b0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
186c0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
186d0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
186e0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
186f0 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
18700 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
18710 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
18720 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
18730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18740 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
18750 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
18760 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
18770 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
18780 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
18790 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
187a0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
187b0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
187c0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
187d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
187e0 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
187f0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18800 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
18810 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
18820 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
18830 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
18840 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
18850 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
18860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18870 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
18880 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
18890 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
188a0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
188b0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
188c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
188d0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
188e0 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
188f0 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
18900 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18910 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
18920 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
18930 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
18940 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
18950 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
18960 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
18970 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
18980 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
18990 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
189a0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
189b0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
189c0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
189d0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
189e0 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
189f0 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
18a00 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
18a10 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
18a20 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
18a30 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
18a40 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
18a50 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
18a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18a70 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
18a80 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
18a90 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
18aa0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
18ab0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
18ac0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
18ad0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
18ae0 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
18af0 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
18b00 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
18b10 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
18b20 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
18b30 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
18b40 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
18b50 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
18b60 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
18b70 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
18b80 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
18b90 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
18ba0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
18bb0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
18bc0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
18bd0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
18be0 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
18bf0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18c00 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
18c10 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
18c20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
18c30 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
18c40 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
18c50 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
18c60 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
18c70 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
18c80 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
18c90 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18ca0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
18cb0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
18cc0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
18cd0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
18ce0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
18cf0 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
18d00 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
18d10 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
18d20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
18d30 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
18d40 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
18d50 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18d60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18d70 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18d80 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18d90 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18da0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
18db0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
18dc0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
18dd0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
18de0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18df0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
18e00 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
18e10 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
18e20 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
18e30 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
18e40 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
18e50 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18e60 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18e70 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
18e80 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
18e90 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
18ea0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
18eb0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
18ec0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
18ed0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18ee0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18ef0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18f00 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18f10 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
18f20 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
18f30 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
18f40 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
18f50 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
18f60 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
18f70 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
18f80 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
18f90 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18fa0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
18fb0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
18fc0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
18fd0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
18fe0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
18ff0 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
19000 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
19010 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
19020 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
19030 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19040 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
19050 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
19060 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
19070 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
19080 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
19090 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
190a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
190b0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
190c0 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a  _TOKENIZER</dt>.
190d0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
190e0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
190f0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
19100 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65  e the two-argume
19110 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  nt.** version of
19120 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e   the [fts3_token
19130 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
19140 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
19150 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
19160 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
19170 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
19180 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
19190 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
191a0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
191b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
191c0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
191d0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
191e0 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
191f0 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
19200 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19210 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
19220 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
19230 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
19240 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
19250 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
19260 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
19270 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
19280 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
19290 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
192a0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
192b0 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
192c0 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
192d0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
192e0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
192f0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
19300 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
19310 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
19320 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
19330 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
19340 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19350 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
19360 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
19370 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19380 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
19390 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ON</dt>.** <dd> 
193a0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
193b0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
193c0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73  r disable the [s
193d0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
193e0 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65  nsion()].** inte
193f0 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e  rface independen
19400 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64  tly of the [load
19410 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51  _extension()] SQ
19420 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  L function..** T
19430 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
19440 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
19450 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73  n()] API enables
19460 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74   or disables bot
19470 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b  h the.** C-API [
19480 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
19490 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68  ension()] and th
194a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b  e SQL function [
194b0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
194c0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
194d0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
194e0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
194f0 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73  ** When the firs
19500 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
19510 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
19520 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65  1, then only the
19530 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61   C-API is.** ena
19540 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  bled and the SQL
19550 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e   function remain
19560 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20  s disabled.  If 
19570 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
19580 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e  nt to.** this in
19590 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68  terface is 0, th
195a0 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50  en both the C-AP
195b0 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  I and the SQL fu
195c0 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62  nction are disab
195d0 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  led..** If the f
195e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
195f0 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61   -1, then no cha
19600 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f  nges are made to
19610 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72   state of either
19620 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72   the.** C-API or
19630 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
19640 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  n..** The second
19650 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19660 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19670 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19680 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19690 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
196a0 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74  e whether [sqlit
196b0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
196c0 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  n()] interface.*
196d0 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  * is disabled or
196e0 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69   enabled followi
196f0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19700 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19710 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20  ter may.** be a 
19720 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
19730 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
19740 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
19750 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
19760 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
19770 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19780 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c  NFIG_MAINDBNAME<
19790 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
197a0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
197b0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
197c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69  name of the "mai
197d0 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73  n" database.** s
197e0 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c  chema.  ^The sol
197f0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
19800 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e  pointer to a con
19810 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e  stant UTF8 strin
19820 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  g.** which will 
19830 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73  become the new s
19840 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c  chema name in pl
19850 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20  ace of "main".  
19860 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20  ^SQLite.** does 
19870 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  not make a copy 
19880 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20  of the new main 
19890 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69  schema name stri
198a0 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69  ng, so the appli
198b0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
198c0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
198d0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
198e0 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49  nto this DBCONFI
198f0 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68  G option is unch
19900 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61  anged.** until a
19910 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73  fter the databas
19920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
19930 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ses..** </dd>.**
19940 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19950 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
19960 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
19970 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
19980 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
19990 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
199a0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
199b0 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
199c0 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
199d0 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
199e0 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
199f0 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
19a00 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
19a10 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
19a20 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
19a30 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
19a40 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
19a50 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
19a60 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
19a70 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
19a80 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
19a90 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
19aa0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
19ab0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19ac0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
19ad0 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
19ae0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70  s an integer - p
19af0 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62  ositive to disab
19b00 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
19b10 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
19b20 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
19b30 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
19b40 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74  , and negative t
19b50 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
19b60 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
19b70 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
19b80 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
19b90 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
19ba0 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
19bb0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
19bc0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
19bd0 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
19be0 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
19bf0 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
19c00 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
19c10 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
19c20 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
19c30 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
19c40 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
19c50 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74  _ENABLE_QPSG</dt
19c60 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  >.** <dd>^(The S
19c70 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19c80 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f  NABLE_QPSG optio
19c90 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
19ca0 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68  eactivates.** th
19cb0 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  e [query planner
19cc0 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61   stability guara
19cd0 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57  ntee] (QPSG).  W
19ce0 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20  hen the QPSG is 
19cf0 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e  active,.** a sin
19d00 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74  gle SQL query st
19d10 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77  atement will alw
19d20 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
19d30 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72   algorithm regar
19d40 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75  dless.** of valu
19d50 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  es of [bound par
19d60 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20  ameters].)^ The 
19d70 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f  QPSG disables so
19d80 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  me query optimiz
19d90 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c  ations.** that l
19da0 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65  ook at the value
19db0 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d  s of bound param
19dc0 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e  eters, which can
19dd0 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69   make some queri
19de0 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42  es.** slower.  B
19df0 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20  ut the QPSG has 
19e00 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66  the advantage of
19e10 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c   more predictabl
19e20 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74  e behavior.  Wit
19e30 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63  h.** the QPSG ac
19e40 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c  tive, SQLite wil
19e50 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
19e60 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e   same query plan
19e70 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73   in the field as
19e80 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72  .** was used dur
19e90 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74  ing testing in t
19ea0 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66  he lab..** The f
19eb0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
19ec0 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
19ed0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
19ee0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
19ef0 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20  e .** the QPSG, 
19f00 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
19f10 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61  le QPSG, or nega
19f20 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
19f30 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
19f40 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f  hanged. The seco
19f50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
19f60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
19f70 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
19f80 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
19f90 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
19fa0 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20  ate whether the 
19fb0 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64  QPSG is disabled
19fc0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
19fd0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
19fe0 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ll..** </dd>.**.
19ff0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
1a000 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45  CONFIG_TRIGGER_E
1a010 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  QP</dt>.** <dd> 
1a020 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
1a030 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49  output of EXPLAI
1a040 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d  N QUERY PLAN com
1a050 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a  mands does not .
1a060 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75  ** include outpu
1a070 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74  t for any operat
1a080 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62  ions performed b
1a090 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  y trigger progra
1a0a0 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69  ms. This.** opti
1a0b0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  on is used to se
1a0c0 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20  t or clear (the 
1a0d0 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20  default) a flag 
1a0e0 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69  that governs thi
1a0f0 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54  s.** behavior. T
1a100 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1a110 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
1a120 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  s operation is a
1a130 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70  n integer -.** p
1a140 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1a150 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69  e output for tri
1a160 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f  gger programs, o
1a170 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c  r zero to disabl
1a180 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61  e it,.** or nega
1a190 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1a1a0 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
1a1b0 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
1a1c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1a1d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1a1e0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
1a1f0 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a  ch is written .*
1a200 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  * 0 or 1 to indi
1a210 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74  cate whether out
1a220 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73  put-for-triggers
1a230 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c   has been disabl
1a240 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74  ed - 0 if .** it
1a250 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64   is not disabled
1a260 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a  , 1 if it is.  .
1a270 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
1a280 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1a290 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53  IG_RESET_DATABAS
1a2a0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 53  E</dt>.** <dd> S
1a2b0 65 74 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  et the SQLITE_DB
1a2c0 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1a2d0 41 42 41 53 45 20 66 6c 61 67 20 61 6e 64 20 74  ABASE flag and t
1a2e0 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41 43 55  hen run.** [VACU
1a2f0 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  UM] in order to 
1a300 72 65 73 65 74 20 61 20 64 61 74 61 62 61 73 65  reset a database
1a310 20 62 61 63 6b 20 74 6f 20 61 6e 20 65 6d 70 74   back to an empt
1a320 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 77 69  y database.** wi
1a330 74 68 20 6e 6f 20 73 63 68 65 6d 61 20 61 6e 64  th no schema and
1a340 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20 54 68 65   no content. The
1a350 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 63 65   following proce
1a360 73 73 20 77 6f 72 6b 73 20 65 76 65 6e 20 66 6f  ss works even fo
1a370 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20 63 6f 72  r.** a badly cor
1a380 72 75 70 74 65 64 20 64 61 74 61 62 61 73 65 20  rupted database 
1a390 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  file:.** <ol>.**
1a3a0 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62   <li> sqlite3_db
1a3b0 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49  _config(db, SQLI
1a3c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45  TE_DBCONFIG_RESE
1a3d0 54 5f 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30  T_DATABASE, 1, 0
1a3e0 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69  );.** <li> [sqli
1a3f0 74 65 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b  te3_exec](db, "[
1a400 56 41 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20  VACUUM]", 0, 0, 
1a410 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  0);.** <li> sqli
1a420 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62  te3_db_config(db
1a430 2c 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  , SQLITE_DBCONFI
1a440 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45  G_RESET_DATABASE
1a450 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c  , 0, 0);.** </ol
1a460 3e 0a 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73  >.** Because res
1a470 65 74 74 69 6e 67 20 61 20 64 61 74 61 62 61 73  etting a databas
1a480 65 20 69 73 20 64 65 73 74 72 75 63 74 69 76 65  e is destructive
1a490 20 61 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c   and irreversibl
1a4a0 65 2c 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73  e, the.** proces
1a4b0 73 20 72 65 71 75 69 72 65 73 20 74 68 65 20 75  s requires the u
1a4c0 73 65 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75  se of this obscu
1a4d0 72 65 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69  re API and multi
1a4e0 70 6c 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c  ple steps to hel
1a4f0 70 0a 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74  p.** ensure that
1a500 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70   it does not hap
1a510 70 65 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e  pen by accident.
1a520 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  .** </dd>.** </d
1a530 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
1a540 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
1a550 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20  INDBNAME        
1a560 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73      1000 /* cons
1a570 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69  t char* */.#defi
1a580 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1a590 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
1a5a0 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a           1001 /*
1a5b0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
1a5c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a5d0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1a5e0 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20  _FKEY           
1a5f0 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1002 /* int int*
1a600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a610 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1a620 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  LE_TRIGGER      
1a630 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e    1003 /* int in
1a640 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1a650 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1a660 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
1a670 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20  ZER 1004 /* int 
1a680 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1a690 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a6a0 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
1a6b0 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e  NSION 1005 /* in
1a6c0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1a6d0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1a6e0 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
1a6f0 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20  SE      1006 /* 
1a700 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1a710 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1a720 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20  FIG_ENABLE_QPSG 
1a730 20 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f            1007 /
1a740 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1a750 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1a760 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51  ONFIG_TRIGGER_EQ
1a770 50 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38  P           1008
1a780 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1a790 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1a7a0 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41  BCONFIG_RESET_DA
1a7b0 54 41 42 41 53 45 20 20 20 20 20 20 20 20 31 30  TABASE        10
1a7c0 30 39 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  09 /* int int* *
1a7d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a7e0 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20  _DBCONFIG_MAX   
1a7f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a800 31 30 30 39 20 2f 2a 20 4c 61 72 67 65 73 74 20  1009 /* Largest 
1a810 44 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a  DBCONFIG */../*.
1a820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
1a830 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
1a840 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
1a850 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  odes.** METHOD: 
1a860 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1a870 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
1a880 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
1a890 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
1a8a0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
1a8b0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
1a8c0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
1a8d0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
1a8e0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
1a8f0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
1a900 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
1a910 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
1a920 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
1a930 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
1a940 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
1a950 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
1a960 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
1a970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a980 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
1a990 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  id.** METHOD: sq
1a9a0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  lite3.**.** ^Eac
1a9b0 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
1a9c0 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
1a9d0 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
1a9e0 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
1a9f0 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
1aa00 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
1aa10 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
1aa20 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
1aa30 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
1aa40 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
1aa50 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
1aa60 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
1aa70 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
1aa80 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
1aa90 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
1aaa0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
1aab0 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
1aac0 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
1aad0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
1aae0 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
1aaf0 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
1ab00 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
1ab10 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
1ab20 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
1ab30 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
1ab40 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
1ab50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1ab60 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1ab70 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
1ab80 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e  e usually return
1ab90 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
1aba0 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63  .** the most rec
1abb0 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b  ent successful [
1abc0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72  INSERT] into a r
1abd0 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76  owid table or [v
1abe0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
1abf0 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e   on database con
1ac00 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65  nection D. ^Inse
1ac10 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55  rts into [WITHOU
1ac20 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20  T ROWID] tables 
1ac30 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72  are not.** recor
1ac40 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63  ded. ^If no succ
1ac50 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
1ac60 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
1ac70 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  es have ever occ
1ac80 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65  urred .** on the
1ac90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1aca0 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c  tion D, then sql
1acb0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1acc0 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
1acd0 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  s .** zero..**.*
1ace0 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69  * As well as bei
1acf0 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63  ng set automatic
1ad00 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65  ally as rows are
1ad10 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64   inserted into d
1ad20 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65  atabase.** table
1ad30 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
1ad40 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
1ad50 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65  nction may be se
1ad60 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a  t explicitly by.
1ad70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1ad80 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1ad90 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  d()].**.** Some 
1ada0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  virtual table im
1adb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
1adc0 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e  y INSERT rows in
1add0 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20  to rowid tables 
1ade0 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f  as.** part of co
1adf0 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73  mmitting a trans
1ae00 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20  action (e.g. to 
1ae10 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d  flush data accum
1ae20 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79  ulated in memory
1ae30 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e  .** to disk). In
1ae40 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65   this case subse
1ae50 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74  quent calls to t
1ae60 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1ae70 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a  urn the rowid.**
1ae80 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1ae90 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20   these internal 
1aea0 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e  INSERT operation
1aeb0 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74  s, which leads t
1aec0 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76  o .** unintuitiv
1aed0 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75  e results. Virtu
1aee0 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
1aef0 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f  ntations that do
1af00 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a   write to rowid.
1af10 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69  ** tables in thi
1af20 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20  s way can avoid 
1af30 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20  this problem by 
1af40 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72  restoring the or
1af50 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64  iginal .** rowid
1af60 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71   value using [sq
1af70 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1af80 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62  nsert_rowid()] b
1af90 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20  efore returning 
1afa0 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74  .** control to t
1afb0 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  he user..**.** ^
1afc0 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
1afd0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
1afe0 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69  trigger then thi
1aff0 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a  s routine will .
1b000 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ** return the [r
1b010 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
1b020 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e  erted row as lon
1b030 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
1b040 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e   is .** running.
1b050 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   Once the trigge
1b060 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20  r program ends, 
1b070 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1b080 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
1b090 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
1b0a0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
1b0b0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
1b0c0 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a   was fired.)^.**
1b0d0 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
1b0e0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
1b0f0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
1b100 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
1b110 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
1b120 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
1b130 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
1b140 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1b150 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
1b160 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
1b170 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
1b180 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
1b190 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
1b1a0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
1b1b0 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
1b1c0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
1b1d0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1b1e0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
1b1f0 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
1b200 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
1b210 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
1b220 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
1b230 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
1b240 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
1b250 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
1b260 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
1b270 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
1b280 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
1b290 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
1b2a0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
1b2b0 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
1b2c0 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
1b2d0 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
1b2e0 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
1b2f0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1b300 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
1b310 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
1b320 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
1b330 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
1b340 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
1b350 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
1b360 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
1b370 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
1b380 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
1b390 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
1b3a0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
1b3b0 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
1b3c0 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
1b3d0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1b3e0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1b3f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1b400 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
1b410 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
1b420 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
1b430 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1b440 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
1b450 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
1b460 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
1b470 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
1b480 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
1b490 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
1b4a0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
1b4b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
1b4c0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
1b4d0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1b4e0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
1b4f0 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
1b500 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
1b510 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
1b520 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
1b530 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
1b540 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
1b550 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1b560 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1b570 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
1b580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1b590 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72  t the Last Inser
1b5a0 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a  t Rowid value..*
1b5b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1b5c0 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
1b5d0 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
1b5e0 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20  ert_rowid(D, R) 
1b5f0 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68  method allows th
1b600 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
1b610 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75  .** set the valu
1b620 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61  e returned by ca
1b630 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61  lling sqlite3_la
1b640 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1b650 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68  D) to R .** with
1b660 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20  out inserting a 
1b670 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74  row into the dat
1b680 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73  abase..*/.void s
1b690 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1b6a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
1b6b0 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  ite3*,sqlite3_in
1b6c0 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
1b6d0 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
1b6e0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1b6f0 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
1b700 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1b710 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1b720 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1b730 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1b740 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  fied, inserted o
1b750 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
1b760 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
1b770 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
1b780 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1b790 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
1b7a0 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  t on the databas
1b7b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
1b7c0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e  cified by the on
1b7d0 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ly parameter..**
1b7e0 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
1b7f0 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
1b800 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
1b810 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
1b820 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1b830 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
1b840 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  on..**.** ^Only 
1b850 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72  changes made dir
1b860 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53  ectly by the INS
1b870 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1b880 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1b890 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
1b8a0 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68  d - auxiliary ch
1b8b0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
1b8c0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
1b8d0 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a  | triggers], .**
1b8e0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1b8f0 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41  tions] or [REPLA
1b900 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
1b910 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f  esolution are no
1b920 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
1b930 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
1b940 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
1b950 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20  ercepted by .** 
1b960 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
1b970 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46  ger | INSTEAD OF
1b980 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e   triggers] are n
1b990 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65  ot counted. ^The
1b9a0 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72   value .** retur
1b9b0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
1b9c0 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61  hanges() immedia
1b9d0 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e  tely after an IN
1b9e0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1b9f0 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
1ba00 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69  ment run on a vi
1ba10 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  ew is always zer
1ba20 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  o. Only changes 
1ba30 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a  made to real .**
1ba40 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e   tables are coun
1ba50 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67  ted..**.** Thing
1ba60 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  s are more compl
1ba70 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71  icated if the sq
1ba80 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1ba90 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65  function is.** e
1baa0 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20  xecuted while a 
1bab0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1bac0 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73  is running. This
1bad0 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74   may happen if t
1bae0 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  he.** program us
1baf0 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  es the [changes(
1bb00 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c  ) SQL function],
1bb10 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65   or if some othe
1bb20 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  r callback.** fu
1bb30 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73  nction invokes s
1bb40 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1bb50 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e   directly. Essen
1bb60 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c  tially:.** .** <
1bb70 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ul>.**   <li> ^(
1bb80 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20  Before entering 
1bb90 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1bba0 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  m the value retu
1bbb0 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
1bbc0 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65    sqlite3_change
1bbd0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  s() function is 
1bbe0 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65  saved. After the
1bbf0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1bc00 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20   .**        has 
1bc10 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72  finished, the or
1bc20 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20  iginal value is 
1bc30 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a  restored.)^.** .
1bc40 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68  **   <li> ^(With
1bc50 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  in a trigger pro
1bc60 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54  gram each INSERT
1bc70 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c  , UPDATE and DEL
1bc80 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73  ETE .**        s
1bc90 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68  tatement sets th
1bca0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1bcb0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
1bcc0 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
1bcd0 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e   upon completion
1bce0 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63   as normal. Of c
1bcf0 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75  ourse, this valu
1bd00 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75  e will not inclu
1bd10 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e  de .**        an
1bd20 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72  y changes perfor
1bd30 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67  med by sub-trigg
1bd40 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69  ers, as the sqli
1bd50 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
1bd60 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77  *        value w
1bd70 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64  ill be saved and
1bd80 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20   restored after 
1bd90 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72  each sub-trigger
1bda0 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c   has run.)^.** <
1bdb0 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69  /ul>.** .** ^Thi
1bdc0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  s means that if 
1bdd0 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51  the changes() SQ
1bde0 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73  L function (or s
1bdf0 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a  imilar) is used.
1be00 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
1be10 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1be20 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1be30 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1be40 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75  ger, it .** retu
1be50 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73  rns the value as
1be60 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61   set when the ca
1be70 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  lling statement 
1be80 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e  began executing.
1be90 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73  .** ^If it is us
1bea0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1beb0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73   or subsequent s
1bec0 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69  uch statement wi
1bed0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a  thin a trigger .
1bee0 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20  ** program, the 
1bef0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72  value returned r
1bf00 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62  eflects the numb
1bf10 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1bf20 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70  ied by the .** p
1bf30 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20  revious INSERT, 
1bf40 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1bf50 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1bf60 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  n the same trigg
1bf70 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
1bf80 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
1bf90 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1bfa0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
1bfb0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
1bfc0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
1bfd0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1bfe0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1bff0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1c000 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1c010 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1c020 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c030 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1c040 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1c050 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1c060 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1c070 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
1c080 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1c090 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1c0a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
1c0b0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1c0c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c0d0 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
1c0e0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
1c0f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1c100 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
1c110 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1c120 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
1c130 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64  of rows inserted
1c140 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a  , modified or.**
1c150 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20   deleted by all 
1c160 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
1c170 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
1c180 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65  tatements comple
1c190 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ted.** since the
1c1a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c1b0 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c  tion was opened,
1c1c0 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65   including those
1c1d0 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20   executed as.** 
1c1e0 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20  part of trigger 
1c1f0 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75  programs. ^Execu
1c200 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
1c210 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
1c220 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ment.** does not
1c230 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75   affect the valu
1c240 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1c250 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1c260 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43  ges()..** .** ^C
1c270 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70  hanges made as p
1c280 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20  art of [foreign 
1c290 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
1c2a0 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
1c2b0 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74  .** count, but t
1c2c0 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72  hose made as par
1c2d0 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  t of REPLACE con
1c2e0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1c2f0 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e  on are.** not. ^
1c300 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1c310 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1c320 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41  cepted by INSTEA
1c330 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a  D OF triggers .*
1c340 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
1c350 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c  d..** .** See al
1c360 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
1c370 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
1c380 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
1c390 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1c3a0 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
1c3b0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
1c3c0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1c3d0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1c3e0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1c3f0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1c400 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c410 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1c420 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1c430 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1c440 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1c450 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
1c460 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1c470 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1c480 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
1c490 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1c4a0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1c4b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
1c4c0 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
1c4d0 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d  nning Query.** M
1c4e0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1c4f0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1c500 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
1c510 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
1c520 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
1c530 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
1c540 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
1c550 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
1c560 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
1c570 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
1c580 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
1c590 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
1c5a0 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
1c5b0 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
1c5c0 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
1c5d0 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
1c5e0 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
1c5f0 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
1c600 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
1c610 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
1c620 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1c630 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
1c640 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
1c650 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
1c660 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
1c670 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
1c680 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
1c690 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
1c6a0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1c6b0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1c6c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c6d0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
1c6e0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
1c6f0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
1c700 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1c710 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
1c720 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
1c730 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
1c740 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
1c750 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
1c760 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
1c770 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
1c780 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
1c790 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
1c7a0 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
1c7b0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
1c7c0 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
1c7d0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
1c7e0 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
1c7f0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
1c800 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
1c810 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
1c820 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
1c830 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
1c840 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
1c850 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
1c860 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
1c870 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
1c880 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
1c890 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
1c8a0 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
1c8b0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
1c8c0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
1c8d0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
1c8e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c8f0 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
1c900 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
1c910 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
1c920 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
1c930 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
1c940 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c950 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
1c960 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
1c970 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1c980 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1c990 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1c9a0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1c9b0 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
1c9c0 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
1c9d0 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
1c9e0 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
1c9f0 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
1ca00 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
1ca10 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
1ca20 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1ca30 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
1ca40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1ca50 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1ca60 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
1ca70 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
1ca80 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
1ca90 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
1caa0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
1cab0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1cac0 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
1cad0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1cae0 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
1caf0 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
1cb00 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
1cb10 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
1cb20 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
1cb30 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
1cb40 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1cb50 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1cb60 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1cb70 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1cb80 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a  all returns..*/.
1cb90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
1cba0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
1cbb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1cbc0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
1cbd0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1cbe0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
1cbf0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1cc00 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
1cc10 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
1cc20 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
1cc30 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
1cc40 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
1cc50 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
1cc60 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
1cc70 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
1cc80 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
1cc90 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
1cca0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
1ccb0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
1ccc0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
1ccd0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
1cce0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
1ccf0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1cd00 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
1cd10 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
1cd20 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
1cd30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
1cd40 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
1cd50 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
1cd60 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
1cd70 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
1cd80 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
1cd90 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
1cda0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
1cdb0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
1cdc0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
1cdd0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
1cde0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
1cdf0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
1ce00 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
1ce10 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
1ce20 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
1ce30 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
1ce40 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
1ce50 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
1ce60 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
1ce70 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
1ce80 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
1ce90 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
1cea0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
1ceb0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
1cec0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
1ced0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
1cee0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
1cef0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1cf00 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
1cf10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
1cf20 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
1cf30 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
1cf40 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
1cf50 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
1cf60 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
1cf70 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1cf80 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
1cf90 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
1cfa0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
1cfb0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
1cfc0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
1cfd0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
1cfe0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
1cff0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
1d000 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
1d010 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1d020 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
1d030 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
1d040 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
1d050 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
1d060 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
1d070 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
1d080 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
1d090 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
1d0a0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
1d0b0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
1d0c0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
1d0d0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
1d0e0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
1d0f0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
1d100 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
1d110 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1d120 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
1d130 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
1d140 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1d150 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1d160 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
1d170 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1d180 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
1d190 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
1d1a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
1d1b0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
1d1c0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1d1d0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
1d1e0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
1d1f0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
1d200 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1d210 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
1d220 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
1d230 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
1d240 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
1d250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1d260 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
1d270 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
1d280 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
1d290 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75  ** KEYWORDS: {bu
1d2a0 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
1d2b0 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c  ack} {busy handl
1d2c0 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
1d2d0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1d2e0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1d2f0 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f  andler(D,X,P) ro
1d300 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
1d310 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1d320 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62  .** that might b
1d330 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
1d340 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
1d350 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
1d360 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1d370 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61  ss a database ta
1d380 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  ble associated w
1d390 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ith.** [database
1d3a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
1d3b0 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hen another thre
1d3c0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
1d3d0 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c   has the table l
1d3e0 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71  ocked..** The sq
1d3f0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1d400 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  er() interface i
1d410 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
1d420 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ent.** [sqlite3_
1d430 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
1d440 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79  and [PRAGMA busy
1d450 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a  _timeout]..**.**
1d460 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1d470 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
1d480 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
1d490 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  Y].** is returne
1d4a0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
1d4b0 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
1d4c0 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
1d4d0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1d4e0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
1d4f0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
1d500 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
1d510 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
1d520 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
1d530 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1d540 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
1d550 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
1d560 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
1d570 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
1d580 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
1d590 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
1d5a0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
1d5b0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
1d5c0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
1d5d0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
1d5e0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
1d5f0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
1d600 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1d610 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
1d620 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79  voked previously
1d630 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
1d640 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
1d650 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
1d660 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
1d670 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
1d680 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
1d690 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
1d6a0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1d6b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
1d6c0 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a  Y] is returned.*
1d6d0 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1d6e0 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
1d6f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d700 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
1d710 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
1d720 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61  .** is made to a
1d730 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1d740 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  se and the cycle
1d750 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
1d760 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
1d770 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
1d780 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
1d790 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
1d7a0 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
1d7b0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
1d7c0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
1d7d0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
1d7e0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
1d7f0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
1d800 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
1d810 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
1d820 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
1d830 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
1d840 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20  ITE_BUSY].** to 
1d850 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1d860 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
1d870 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79  ing the .** busy
1d880 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
1d890 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
1d8a0 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
1d8b0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1d8c0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
1d8d0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
1d8e0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
1d8f0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
1d900 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
1d910 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1d920 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1d930 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
1d940 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
1d950 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
1d960 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
1d970 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
1d980 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
1d990 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1d9a0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
1d9b0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
1d9c0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
1d9d0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
1d9e0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1d9f0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
1da00 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
1da10 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
1da20 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
1da30 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
1da40 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
1da50 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
1da60 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
1da70 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
1da80 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
1da90 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
1daa0 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
1dab0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1dac0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
1dad0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
1dae0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
1daf0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
1db00 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
1db10 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
1db20 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
1db30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1db40 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1db50 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1db60 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
1db70 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1db80 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
1db90 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
1dba0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
1dbb0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
1dbc0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
1dbd0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
1dbe0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1dbf0 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f  _timeout()].** o
1dc00 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52  r evaluating [PR
1dc10 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1dc20 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65  t=N] will change
1dc30 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
1dc40 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c  dler and thus cl
1dc50 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ear any previous
1dc60 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64  ly set busy hand
1dc70 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
1dc80 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
1dc90 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
1dca0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
1dcb0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
1dcc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1dcd0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1dce0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
1dcf0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
1dd00 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1dd10 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e  dler is not reen
1dd20 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68  trant.  Any such
1dd30 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
1dd40 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
1dd50 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
1dd60 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
1dd70 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
1dd80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1dd90 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
1dda0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ddb0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
1ddc0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1ddd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1dde0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
1ddf0 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69  ite3*,int(*)(voi
1de00 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a  d*,int),void*);.
1de10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1de20 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
1de30 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  out.** METHOD: s
1de40 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1de50 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
1de60 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
1de70 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
1de80 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
1de90 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
1dea0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
1deb0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
1dec0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
1ded0 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
1dee0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
1def0 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
1df00 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1df10 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1df20 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
1df30 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
1df40 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
1df50 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1df60 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
1df70 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
1df80 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
1df90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1dfa0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
1dfb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
1dfc0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
1dfd0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1dfe0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
1dff0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
1e000 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
1e010 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
1e020 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
1e030 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1e040 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1e050 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
1e060 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1e070 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1e080 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  at any given mom
1e090 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1e0a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1e0b0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1e0c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1e0d0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1e0e0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1e0f0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1e100 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1e110 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1e120 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  red.)^.**.** See
1e130 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20   also:  [PRAGMA 
1e140 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f  busy_timeout].*/
1e150 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
1e160 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
1e170 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
1e180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1e190 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
1e1a0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
1e1b0 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ueries.** METHOD
1e1c0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1e1d0 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
1e1e0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1e1f0 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
1e200 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1e210 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
1e220 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1e230 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
1e240 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
1e250 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
1e260 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
1e270 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
1e280 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
1e290 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
1e2a0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1e2b0 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
1e2c0 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
1e2d0 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
1e2e0 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
1e2f0 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
1e300 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
1e310 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
1e320 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
1e330 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
1e340 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
1e350 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
1e360 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
1e370 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1e380 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
1e390 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
1e3a0 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
1e3b0 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
1e3c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1e3d0 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
1e3e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1e3f0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
1e400 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
1e410 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
1e420 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1e430 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1e440 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
1e450 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
1e460 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
1e470 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
1e480 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
1e490 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1e4a0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
1e4b0 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
1e4c0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
1e4d0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
1e4e0 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
1e4f0 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
1e500 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
1e510 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
1e520 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
1e530 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
1e540 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
1e550 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1e560 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
1e570 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
1e580 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1e590 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1e5a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
1e5b0 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
1e5c0 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
1e5d0 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
1e5e0 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
1e5f0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1e600 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
1e610 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
1e620 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e630 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
1e640 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
1e650 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
1e660 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1e670 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
1e680 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
1e690 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1e6a0 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
1e6b0 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
1e6c0 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
1e6d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e6e0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1e6f0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
1e700 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
1e710 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
1e720 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
1e730 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
1e740 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
1e750 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
1e760 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
1e770 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
1e780 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1e790 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
1e7a0 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
1e7b0 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
1e7c0 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
1e7d0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
1e7e0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
1e7f0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
1e800 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1e810 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
1e820 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
1e830 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
1e840 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
1e850 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
1e860 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1e870 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1e880 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
1e890 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
1e8a0 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
1e8b0 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
1e8c0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
1e8d0 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
1e8e0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1e8f0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
1e900 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1e910 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
1e920 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1e930 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
1e940 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
1e950 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
1e960 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
1e970 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1e980 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
1e990 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e9a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1e9b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1e9c0 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
1e9d0 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
1e9e0 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
1e9f0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
1ea00 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
1ea10 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1ea20 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
1ea30 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
1ea40 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
1ea50 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
1ea60 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
1ea70 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
1ea80 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
1ea90 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
1eaa0 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
1eab0 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
1eac0 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
1ead0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
1eae0 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
1eaf0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1eb00 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
1eb10 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1eb20 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
1eb30 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1eb40 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
1eb50 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
1eb60 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
1eb70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1eb80 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
1eb90 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
1eba0 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
1ebb0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
1ebc0 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
1ebd0 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
1ebe0 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
1ebf0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
1ec00 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
1ec10 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
1ec20 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
1ec30 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
1ec40 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
1ec50 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1ec60 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
1ec70 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
1ec80 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
1ec90 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1eca0 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
1ecb0 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
1ecc0 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
1ecd0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
1ece0 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
1ecf0 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
1ed00 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
1ed10 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
1ed20 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
1ed30 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
1ed40 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
1ed50 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
1ed60 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
1ed70 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
1ed80 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
1ed90 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1eda0 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
1edb0 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
1edc0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1edd0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
1ede0 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
1edf0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
1ee00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
1ee10 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1ee20 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1ee30 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1ee40 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1ee50 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1ee60 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1ee70 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1ee80 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1ee90 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1eea0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1eeb0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1eec0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1eed0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1eee0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1eef0 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1ef00 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1ef10 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1ef20 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1ef30 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1ef40 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1ef50 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1ef60 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
1ef70 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1ef80 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1ef90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1efa0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1efb0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1efc0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1efd0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1efe0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1eff0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1f000 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1f010 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1f020 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1f030 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  y..** These rout
1f040 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20  ines understand 
1f050 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d  most of the comm
1f060 6f 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  on formatting op
1f070 74 69 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68  tions from.** th
1f080 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61  e standard libra
1f090 72 79 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20  ry printf() .** 
1f0a0 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1f0b0 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1f0c0 64 20 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c  d formats ([%q],
1f0d0 20 5b 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64   [%Q], [%w], and
1f0e0 20 5b 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74   [%z])..** See t
1f0f0 68 65 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69  he [built-in pri
1f100 6e 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61  ntf()] documenta
1f110 74 69 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c 73  tion for details
1f120 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1f130 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
1f140 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
1f150 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
1f160 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
1f170 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
1f180 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1f190 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36  [sqlite3_malloc6
1f1a0 34 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  4()]..** The str
1f1b0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1f1c0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1f1d0 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1f1e0 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1f1f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1f200 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1f210 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1f220 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1f230 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20  te3_malloc64()] 
1f240 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1f250 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1f260 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1f270 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1f280 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1f290 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1f2a0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1f2b0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1f2c0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1f2d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1f2e0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1f2f0 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1f300 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1f310 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1f320 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1f330 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1f340 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1f350 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1f360 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1f370 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1f380 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1f390 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1f3a0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1f3b0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1f3c0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1f3d0 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1f3e0 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1f3f0 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1f400 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1f410 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1f420 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1f430 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1f440 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1f450 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1f460 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1f470 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1f480 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1f490 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1f4a0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1f4b0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1f4c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1f4d0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1f4e0 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1f4f0 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1f500 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1f510 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1f520 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1f530 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1f540 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1f550 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1f560 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1f570 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1f580 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1f590 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1f5a0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1f5b0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1f5c0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1f5d0 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1f5e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1f5f0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1f600 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1f610 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1f620 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1f630 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1f640 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1f650 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1f660 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1f670 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1f680 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1f690 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1f6a0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1f6b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1f6c0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1f6d0 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1f6e0 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1f6f0 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1f700 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75  * See also:  [bu
1f710 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d  ilt-in printf()]
1f720 2c 20 5b 70 72 69 6e 74 66 28 29 20 53 51 4c 20  , [printf() SQL 
1f730 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61  function].*/.cha
1f740 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1f750 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1f760 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1f770 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1f780 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1f790 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1f7a0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1f7b0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1f7c0 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
1f7d0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1f7e0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1f7f0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1f800 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f810 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1f820 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1f830 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1f840 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1f850 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1f860 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1f870 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1f880 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1f890 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1f8a0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1f8b0 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1f8c0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1f8d0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1f8e0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1f8f0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1f900 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1f910 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1f920 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1f930 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1f940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f950 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1f960 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1f970 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1f980 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1f990 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1f9a0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1f9b0 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1f9c0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1f9d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1f9e0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1f9f0 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1fa00 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1fa10 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1fa20 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1fa30 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1fa40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1fa50 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1fa60 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1fa70 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1fa80 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1fa90 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1faa0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1fab0 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1fac0 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1fad0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1fae0 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1faf0 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1fb00 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1fb10 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1fb20 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1fb30 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1fb40 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1fb50 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1fb60 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1fb70 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1fb80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1fb90 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fba0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1fbb0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1fbc0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1fbd0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1fbe0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1fbf0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1fc00 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1fc10 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1fc20 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1fc30 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1fc40 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1fc50 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1fc60 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1fc70 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1fc80 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1fc90 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1fca0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1fcb0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1fcc0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1fcd0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1fce0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1fcf0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1fd00 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1fd10 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1fd20 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1fd30 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1fd40 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1fd50 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1fd60 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1fd70 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1fd80 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1fd90 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1fda0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1fdb0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1fdc0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1fdd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1fde0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1fdf0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1fe00 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1fe10 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1fe20 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1fe30 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1fe40 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1fe50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1fe60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1fe70 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1fe80 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1fe90 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1fea0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1feb0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1fec0 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1fed0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1fee0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1fef0 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1ff00 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1ff10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1ff20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1ff30 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1ff40 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1ff50 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1ff60 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1ff70 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1ff80 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1ff90 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1ffa0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1ffb0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1ffc0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1ffd0 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1ffe0 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1fff0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
20000 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
20010 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
20020 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
20030 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
20040 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
20050 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
20060 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
20070 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
20080 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
20090 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
200a0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
200b0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
200c0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
200d0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
200e0 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
200f0 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
20100 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
20110 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
20120 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
20130 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
20140 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
20150 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
20160 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
20170 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
20180 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
20190 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
201a0 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
201b0 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
201c0 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
201d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
201e0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
201f0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
20200 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
20210 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
20220 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
20230 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
20240 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
20250 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
20260 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
20270 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
20280 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20290 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
202a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
202b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
202c0 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
202d0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
202e0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
202f0 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
20300 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
20310 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
20320 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
20330 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
20340 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
20350 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
20360 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
20370 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
20380 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
20390 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
203a0 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
203b0 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
203c0 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
203d0 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
203e0 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
203f0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
20400 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
20410 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
20420 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
20430 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
20440 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
20450 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
20460 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
20470 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
20480 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
20490 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
204a0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
204b0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
204c0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
204d0 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
204e0 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
204f0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
20500 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
20510 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
20520 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
20530 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
20540 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
20550 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
20560 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
20570 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
20580 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
20590 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
205a0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
205b0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
205c0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
205d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
205e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
205f0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
20600 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
20610 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
20620 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
20630 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
20640 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
20650 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
20660 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
20670 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
20680 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
20690 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
206a0 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
206b0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
206c0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
206d0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
206e0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
206f0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
20700 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
20710 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
20720 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
20730 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
20740 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
20750 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
20760 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
20770 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
20780 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
20790 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
207a0 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
207b0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
207c0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
207d0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
207e0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
207f0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
20800 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
20810 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
20820 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
20830 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
20840 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
20850 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
20860 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
20870 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
20880 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
20890 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
208a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
208b0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
208c0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
208d0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
208e0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
208f0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
20900 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
20910 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
20920 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
20930 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
20940 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
20950 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
20960 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
20970 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
20980 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
20990 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
209a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
209b0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
209c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
209d0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
209e0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
209f0 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
20a00 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
20a10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
20a20 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69  ree(void*);.sqli
20a30 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
20a40 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
20a50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20a60 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
20a70 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
20a80 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
20a90 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
20aa0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
20ab0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
20ac0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
20ad0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20ae0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
20af0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
20b00 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
20b10 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
20b20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
20b30 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
20b40 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
20b50 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
20b60 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
20b70 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
20b80 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
20b90 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
20ba0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
20bb0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
20bc0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
20bd0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
20be0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20bf0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
20c00 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
20c10 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
20c20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20c30 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
20c40 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
20c50 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
20c60 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
20c70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
20c80 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20c90 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
20ca0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20cb0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
20cc0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
20cd0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
20ce0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
20cf0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
20d00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
20d10 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
20d20 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
20d30 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
20d40 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
20d50 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
20d60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20d70 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
20d80 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
20d90 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
20da0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
20db0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
20dc0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
20dd0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
20de0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
20df0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
20e00 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20e10 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
20e20 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
20e30 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
20e40 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20e50 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
20e60 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
20e70 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
20e80 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
20e90 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
20ea0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
20eb0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
20ec0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
20ed0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
20ee0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
20ef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
20f00 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
20f10 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
20f20 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
20f30 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
20f40 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
20f50 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
20f60 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
20f70 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
20f80 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
20f90 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
20fa0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
20fb0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
20fc0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
20fd0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
20fe0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
20ff0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
21000 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
21010 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
21020 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
21030 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
21040 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
21050 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
21060 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
21070 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
21080 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
21090 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
210a0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
210b0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
210c0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
210d0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
210e0 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
210f0 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
21100 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
21110 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
21120 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
21130 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
21140 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
21150 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
21160 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
21170 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21180 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
21190 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
211a0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
211b0 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
211c0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
211d0 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
211e0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
211f0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
21200 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
21210 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
21220 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
21230 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
21240 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
21250 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
21260 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
21270 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
21280 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
21290 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
212a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
212b0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
212c0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
212d0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
212e0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
212f0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
21300 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
21310 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
21320 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  n Callbacks.** M
21330 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
21340 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
21350 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21360 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  }.**.** ^This ro
21370 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
21380 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
21390 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
213a0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
213b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
213c0 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
213d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
213e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
213f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21400 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
21410 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
21420 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
21430 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
21440 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
21450 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
21460 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
21470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21480 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c  pare_v3()], [sql
21490 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
214a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
214b0 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20  are16_v2()],.** 
214c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
214d0 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e  pare16_v3()].  ^
214e0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
214f0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
21500 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
21510 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
21520 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
21530 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
21540 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
21550 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21560 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
21570 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
21580 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
21590 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
215a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
215b0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
215c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
215d0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
215e0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
215f0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
21600 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
21610 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
21620 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
21630 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
21640 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
21650 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
21660 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
21670 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
21680 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
21690 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
216a0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
216b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
216c0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
216d0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
216e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
216f0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
21700 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
21710 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
21720 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21730 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
21740 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
21750 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
21760 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
21770 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
21780 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
21790 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
217a0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
217b0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
217c0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
217d0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
217e0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
217f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
21800 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
21810 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
21820 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
21830 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
21840 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
21850 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
21860 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
21870 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
21880 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
21890 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
218a0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
218b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
218c0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
218d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
218e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
218f0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
21900 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
21910 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
21920 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
21930 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
21940 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
21950 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
21960 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
21970 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
21980 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
21990 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
219a0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
219b0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
219c0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
219d0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
219e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
219f0 20 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c   are either NULL
21a00 20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72   pointers or zer
21a10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
21a20 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e  ings.** that con
21a30 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  tain additional 
21a40 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
21a50 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
21a60 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70  uthorized..** Ap
21a70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
21a80 61 6c 77 61 79 73 20 62 65 20 70 72 65 70 61 72  always be prepar
21a90 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20  ed to encounter 
21aa0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
21ab0 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  n any.** of the 
21ac0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 74 68  third through th
21ad0 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
21ae0 72 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72  rs of the author
21af0 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
21b00 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
21b10 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
21b20 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
21b30 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
21b40 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
21b50 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
21b60 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
21b70 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
21b80 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
21b90 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
21ba0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
21bb0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
21bc0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
21bd0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
21be0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
21bf0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
21c00 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
21c10 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
21c20 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
21c30 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
21c40 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
21c50 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
21c60 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
21c70 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
21c80 20 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69   ^When a table i
21c90 73 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20  s referenced by 
21ca0 61 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e  a [SELECT] but n
21cb0 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20  o column values 
21cc0 61 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64  are.** extracted
21cd0 20 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65   from that table
21ce0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e   (for example in
21cf0 20 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a   a query like.**
21d00 20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a   "SELECT count(*
21d10 29 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65  ) FROM tab") the
21d20 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45  n the [SQLITE_RE
21d30 41 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63  AD] authorizer c
21d40 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e  allback.** is in
21d50 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74  voked once for t
21d60 68 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 61  hat table with a
21d70 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61   column name tha
21d80 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  t is an empty st
21d90 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
21da0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
21db0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
21dc0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
21dd0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
21de0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
21df0 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
21e00 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
21e10 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
21e20 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
21e30 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
21e40 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
21e50 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
21e60 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
21e70 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
21e80 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
21e90 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
21ea0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
21eb0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
21ec0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
21ed0 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
21ee0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
21ef0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
21f00 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
21f10 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
21f20 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
21f30 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
21f40 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
21f50 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
21f60 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
21f70 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
21f80 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
21f90 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
21fa0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
21fb0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
21fc0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
21fd0 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
21fe0 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
21ff0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
22000 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
22010 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
22020 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
22030 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
22040 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
22050 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
22060 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
22070 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
22080 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
22090 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
220a0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
220b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
220c0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
220d0 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
220e0 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
220f0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
22100 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
22110 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
22120 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
22130 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
22140 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
22150 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
22160 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
22170 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
22180 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
22190 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
221a0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
221b0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
221c0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
221d0 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
221e0 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
221f0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
22200 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
22210 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
22220 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
22230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22240 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
22250 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
22260 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
22270 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
22280 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
22290 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
222a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
222b0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
222c0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
222d0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
222e0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
222f0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
22300 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22310 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
22320 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
22330 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
22340 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
22350 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
22360 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
22370 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
22380 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
22390 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
223a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
223b0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
223c0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
223d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
223e0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
223f0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
22400 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
22410 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
22420 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22430 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
22440 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
22450 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
22460 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
22470 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
22480 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22490 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
224a0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
224b0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
224c0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
224d0 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
224e0 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
224f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
22500 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
22510 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
22520 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
22530 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
22540 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22550 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
22560 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
22570 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
22580 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
22590 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
225a0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
225b0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
225c0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
225d0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
225e0 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
225f0 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
22600 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
22610 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
22620 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
22630 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22640 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
22650 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
22660 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
22670 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22680 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
22690 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
226a0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
226b0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
226c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
226d0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
226e0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
226f0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
22700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
22710 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
22720 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
22730 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
22740 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
22750 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
22760 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
22770 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
22780 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
22790 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
227a0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
227b0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
227c0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
227d0 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
227e0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
227f0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
22800 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22810 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
22820 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
22830 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
22840 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
22850 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
22860 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
22870 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e  o used as a [con
22880 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
22890 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e   mode].** return
228a0 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ed from the [sql
228b0 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
228c0 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
228d0 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
228e0 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
228f0 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
22900 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
22910 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
22920 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
22930 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
22940 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
22950 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
22960 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
22970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
22980 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
22990 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
229a0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
229b0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
229c0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
229d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
229e0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
229f0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
22a00 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
22a10 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
22a20 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
22a30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
22a40 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
22a50 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
22a60 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
22a70 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
22a80 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
22a90 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
22aa0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
22ab0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
22ac0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22ad0 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
22ae0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
22af0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
22b00 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
22b10 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
22b20 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
22b30 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
22b40 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
22b50 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
22b60 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
22b70 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
22b80 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
22b90 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
22ba0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
22bb0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
22bc0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
22bd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
22be0 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
22bf0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
22c00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22c10 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
22c20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
22c30 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
22c40 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
22c50 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
22c60 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
22c70 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
22c80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
22c90 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
22ca0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
22cb0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
22cc0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
22cd0 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
22ce0 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
22cf0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
22d00 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
22d10 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
22d20 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
22d30 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
22d40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
22d60 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
22d70 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
22d80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22d90 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
22da0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
22db0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22dc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22dd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22de0 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
22df0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
22e00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22e10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22e20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22e30 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
22e40 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
22e50 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
22e60 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22e80 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
22e90 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
22ea0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22eb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22ec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22ed0 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
22ee0 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
22ef0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
22f00 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22f10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22f20 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
22f30 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
22f40 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
22f50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22f60 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22f70 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
22f80 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
22f90 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22fa0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22fb0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22fc0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
22fd0 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
22fe0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22ff0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23000 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
23010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
23020 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
23030 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23040 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23050 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
23060 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
23070 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
23080 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
23090 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
230a0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
230b0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
230c0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
230d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
230e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
230f0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
23100 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
23110 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
23120 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
23130 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23140 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
23150 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
23160 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
23170 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23180 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23190 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
231a0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
231b0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
231c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
231d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
231e0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
231f0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
23200 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
23210 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23230 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
23240 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
23250 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
23260 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
23270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23280 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
23290 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
232a0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
232b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
232c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
232d0 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
232e0 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
232f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
23300 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
23320 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
23330 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
23340 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
23350 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
23360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
23370 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
23380 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
23390 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
233a0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
233b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
233c0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
233d0 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
233e0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
233f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23400 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
23410 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
23420 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
23430 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
23440 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23450 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
23460 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
23470 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
23480 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
23490 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
234a0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
234b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
234c0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
234d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
234e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
234f0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
23500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
23510 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
23520 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
23530 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23540 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
23550 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
23560 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
23570 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
23580 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23590 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
235a0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
235b0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
235c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
235d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
235e0 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
235f0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
23600 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23610 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23620 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23630 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
23640 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
23650 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
23660 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
23670 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23680 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
23690 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
236a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
236b0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
236c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
236d0 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
236e0 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
236f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23700 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
23710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23720 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
23730 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
23740 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
23750 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
23760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23770 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
23780 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
23790 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
237a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
237b0 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
237c0 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
237d0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
237e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
237f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23800 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
23810 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
23820 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
23830 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e3.**.** These r
23840 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72  outines are depr
23850 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20  ecated. Use the 
23860 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
23870 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  2()] interface.*
23880 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  * instead of the
23890 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69   routines descri
238a0 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  bed here..**.** 
238b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
238c0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
238d0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
238e0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
238f0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
23900 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
23910 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
23920 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
23930 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
23940 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
23950 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
23960 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
23970 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
23980 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
23990 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
239a0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
239b0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
239c0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
239d0 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
239e0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
239f0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
23a00 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
23a10 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
23a20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
23a30 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
23a40 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
23a50 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
23a60 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
23a70 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
23a80 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
23a90 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
23aa0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
23ab0 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
23ac0 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
23ad0 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
23ae0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
23af0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
23b00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
23b10 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
23b20 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
23b30 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
23b40 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
23b50 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
23b60 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
23b70 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
23b80 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
23b90 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
23ba0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
23bb0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
23bc0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
23bd0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
23be0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
23bf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
23c00 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
23c10 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
23c20 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
23c30 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
23c40 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
23c50 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
23c60 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
23c70 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
23c80 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
23c90 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
23ca0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
23cb0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
23cc0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
23cd0 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
23ce0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
23cf0 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
23d00 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
23d10 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
23d20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
23d30 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
23d40 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
23d50 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
23d60 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
23d70 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
23d80 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
23d90 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
23da0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
23db0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
23dc0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
23dd0 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
23de0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
23df0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
23e00 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
23e10 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
23e20 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
23e30 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44  ite..*/.SQLITE_D
23e40 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a  EPRECATED void *
23e50 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
23e60 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
23e70 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
23e80 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
23e90 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  d*);.SQLITE_DEPR
23ea0 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c  ECATED void *sql
23eb0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
23ec0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
23ed0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
23ee0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
23ef0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
23f00 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
23f10 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20  3REF: SQL Trace 
23f20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  Event Codes.** K
23f30 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
23f40 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73  TRACE.**.** Thes
23f50 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e  e constants iden
23f60 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20  tify classes of 
23f70 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20  events that can 
23f80 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20  be monitored.** 
23f90 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
23fa0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74  e3_trace_v2()] t
23fb0 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54  racing logic.  T
23fc0 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  he M argument.**
23fd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
23fe0 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d 20  ce_v2(D,M,X,P)] 
23ff0 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62  is an OR-ed comb
24000 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f  ination of one o
24010 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65  r more of.** the
24020 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74   following const
24030 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73  ants.  ^The firs
24040 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
24050 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
24060 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  .** is one of th
24070 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73  e following cons
24080 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  tants..**.** New
24090 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e   tracing constan
240a0 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ts may be added 
240b0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
240c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61  es..**.** ^A tra
240d0 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20  ce callback has 
240e0 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20  four arguments: 
240f0 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c  xCallback(T,C,P,
24100 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72  X)..** ^The T ar
24110 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
24120 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79 70   the integer typ
24130 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a  e codes above..*
24140 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e  * ^The C argumen
24150 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  t is a copy of t
24160 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  he context point
24170 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  er passed in as 
24180 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72  the.** fourth ar
24190 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
241a0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a  e3_trace_v2()]..
241b0 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61  ** The P and X a
241c0 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69  rguments are poi
241d0 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e  nters whose mean
241e0 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54  ings depend on T
241f0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
24200 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  [[SQLITE_TRACE_S
24210 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TMT]] <dt>SQLITE
24220 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e  _TRACE_STMT</dt>
24230 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
24240 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61  TE_TRACE_STMT ca
24250 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
24260 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72 65  d when a prepare
24270 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66  d statement.** f
24280 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e  irst begins runn
24290 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ing and possibly
242a0 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20   at other times 
242b0 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78  during the.** ex
242c0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70  ecution of the p
242d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
242e0 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74 68  t, such as at th
242f0 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a  e start of each.
24300 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70 72  ** trigger subpr
24310 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72  ogram. ^The P ar
24320 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
24330 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70  ter to the.** [p
24340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24350 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d  t]. ^The X argum
24360 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
24370 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
24380 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65  ch.** is the une
24390 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74  xpanded SQL text
243a0 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
243b0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e   statement or an
243c0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a   SQL comment .**
243d0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
243e0 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  the invocation o
243f0 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54  f a trigger.  ^T
24400 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20  he callback can 
24410 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73  compute.** the s
24420 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77 6f  ame text that wo
24430 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72 65  uld have been re
24440 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65  turned by the le
24450 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72  gacy [sqlite3_tr
24460 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ace()].** interf
24470 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68 65  ace by using the
24480 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e   X argument when
24490 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20 22   X begins with "
244a0 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  --" and invoking
244b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70  .** [sqlite3_exp
244c0 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74  anded_sql(P)] ot
244d0 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b  herwise..**.** [
244e0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52  [SQLITE_TRACE_PR
244f0 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  OFILE]] <dt>SQLI
24500 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
24510 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
24520 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
24530 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70  OFILE callback p
24540 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d  rovides approxim
24550 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a  ately the same.*
24560 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  * information as
24570 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
24580 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  the [sqlite3_pro
24590 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b  file()] callback
245a0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75  ..** ^The P argu
245b0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
245c0 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
245d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
245e0 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
245f0 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
24600 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77  64-bit integer w
24610 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74 69  hich is the esti
24620 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20  mated of.** the 
24630 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65  number of nanose
24640 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70 72  cond that the pr
24650 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24660 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
24670 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41   ^The SQLITE_TRA
24680 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62  CE_PROFILE callb
24690 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
246a0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
246b0 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a  t finishes..**.*
246c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
246d0 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _ROW]] <dt>SQLIT
246e0 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e  E_TRACE_ROW</dt>
246f0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
24700 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c  TE_TRACE_ROW cal
24710 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
24720 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65 70   whenever a prep
24730 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
24740 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73 69  t generates a si
24750 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75  ngle row of resu
24760 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20  lt.  .** ^The P 
24770 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
24780 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72  inter to the [pr
24790 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
247a0 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61  ] and the.** X a
247b0 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65  rgument is unuse
247c0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d..**.** [[SQLIT
247d0 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20  E_TRACE_CLOSE]] 
247e0 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
247f0 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
24800 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
24810 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61  ACE_CLOSE callba
24820 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
24830 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  en a database.**
24840 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
24850 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  es..** ^The P ar
24860 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
24870 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
24880 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
24890 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74   object.** and t
248a0 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  he X argument is
248b0 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c   unused..** </dl
248c0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
248d0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20  ITE_TRACE_STMT  
248e0 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e       0x01.#defin
248f0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
24900 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23  ROFILE    0x02.#
24910 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
24920 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30  ACE_ROW        0
24930 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x04.#define SQLI
24940 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20  TE_TRACE_CLOSE  
24950 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20      0x08../*.** 
24960 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72  CAPI3REF: SQL Tr
24970 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48  ace Hook.** METH
24980 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
24990 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
249a0 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29  race_v2(D,M,X,P)
249b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
249c0 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61 6c  ters a trace cal
249d0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
249e0 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74  n X against [dat
249f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24a00 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65  ] D, using prope
24a10 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e  rty mask M.** an
24a20 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  d context pointe
24a30 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20  r P.  ^If the X 
24a40 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e  callback is.** N
24a50 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20  ULL or if the M 
24a60 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68  mask is zero, th
24a70 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64 69  en tracing is di
24a80 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  sabled.  The.** 
24a90 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  M argument shoul
24aa0 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73 65  d be the bitwise
24ab0 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
24ac0 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72  on of.** zero or
24ad0 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52   more [SQLITE_TR
24ae0 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  ACE] constants..
24af0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c  **.** ^Each call
24b00 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74   to either sqlit
24b10 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71  e3_trace() or sq
24b20 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
24b30 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28   overrides .** (
24b40 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69  cancels) any pri
24b50 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  or calls to sqli
24b60 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73  te3_trace() or s
24b70 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24b80 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20  )..**.** ^The X 
24b90 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
24ba0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79  ked whenever any
24bb0 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20 69   of the events i
24bc0 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a  dentified by .**
24bd0 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20   mask M occur.  
24be0 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65 74  ^The integer ret
24bf0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74  urn value from t
24c00 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63  he callback is c
24c10 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f  urrently.** igno
24c20 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73  red, though this
24c30 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66   may change in f
24c40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20  uture releases. 
24c50 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70   Callback.** imp
24c60 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
24c70 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20  uld return zero 
24c80 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72 65  to ensure future
24c90 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
24ca0 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
24cb0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
24cc0 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72 67  ed with four arg
24cd0 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b  uments: callback
24ce0 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
24cf0 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
24d00 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c   one of the [SQL
24d10 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f  ITE_TRACE].** co
24d20 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63  nstants to indic
24d30 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c  ate why the call
24d40 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64  back was invoked
24d50 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75  ..** ^The C argu
24d60 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f  ment is a copy o
24d70 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f  f the context po
24d80 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20  inter..** The P 
24d90 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
24da0 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
24db0 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
24dc0 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54  nd on T..**.** T
24dd0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
24de0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
24df0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72  is intended to r
24e00 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63  eplace the legac
24e10 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
24e20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
24e30 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
24e40 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20  rofile()], both 
24e50 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20  of which.** are 
24e60 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69  deprecated..*/.i
24e70 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  nt sqlite3_trace
24e80 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
24e90 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73  .  unsigned uMas
24ea0 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62  k,.  int(*xCallb
24eb0 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f  ack)(unsigned,vo
24ec0 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29  id*,void*,void*)
24ed0 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29  ,.  void *pCtx.)
24ee0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24ef0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
24f00 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  s Callbacks.** M
24f10 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
24f20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
24f30 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
24f40 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
24f50 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
24f60 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
24f70 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
24f80 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
24f90 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
24fa0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
24fb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
24fc0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
24fd0 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
24fe0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
24ff0 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
25000 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
25010 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
25020 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
25030 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
25040 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
25050 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
25060 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
25070 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
25080 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
25090 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
250a0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
250b0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
250c0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
250d0 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f  r N is the appro
250e0 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66  ximate number of
250f0 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
25100 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
25110 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
25120 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
25130 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
25140 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
25150 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66  callback X.  ^If
25160 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
25170 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f  one then the pro
25180 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72  gress.** handler
25190 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
251a0 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
251b0 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
251c0 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
251d0 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
251e0 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
251f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
25200 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
25210 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
25220 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
25230 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
25240 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
25250 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
25260 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
25270 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
25280 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
25290 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
252a0 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
252b0 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
252c0 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
252d0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
252e0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
252f0 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
25300 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
25310 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
25320 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
25330 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
25340 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
25350 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
25360 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
25370 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
25380 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
25390 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
253a0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
253b0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
253c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
253d0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
253e0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
253f0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
25400 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
25410 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
25420 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25430 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
25440 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
25450 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
25460 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
25470 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
25480 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
25490 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
254a0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
254b0 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
254c0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
254d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
254e0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
254f0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
25500 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52  ection.** CONSTR
25510 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a  UCTOR: sqlite3.*
25520 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
25530 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
25540 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
25550 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
25560 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
25570 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
25580 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
25590 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
255a0 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
255b0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
255c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
255d0 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
255e0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
255f0 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
25600 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
25610 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
25620 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25630 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
25640 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
25650 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
25660 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
25670 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
25680 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
25690 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
256a0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
256b0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
256c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
256d0 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
256e0 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
256f0 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
25700 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
25710 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
25720 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
25730 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
25740 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
25750 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
25760 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
25770 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
25780 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
25790 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
257a0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
257b0 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
257c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
257d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
257e0 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
257f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
25800 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
25810 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
25820 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
25830 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
25840 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
25850 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
25860 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
25870 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
25880 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
25890 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66   will be UTF-8 f
258a0 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65  or databases cre
258b0 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71  ated using.** sq
258c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
258d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
258e0 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  ).  ^The default
258f0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61   encoding for da
25900 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74  tabases.** creat
25910 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
25920 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62  _open16() will b
25930 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  e UTF-16 in the 
25940 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
25950 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  r..**.** Whether
25960 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
25970 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
25980 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
25990 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
259a0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
259b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
259c0 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
259d0 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
259e0 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
259f0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
25a00 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
25a10 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
25a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25a30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
25a40 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
25a50 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
25a60 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
25a70 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
25a80 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
25a90 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
25aa0 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
25ab0 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
25ac0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
25ad0 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
25ae0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
25af0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25b00 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
25b10 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
25b20 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
25b30 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
25b40 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
25b50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
25b60 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
25b70 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
25b80 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
25b90 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
25ba0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
25bb0 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
25bc0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
25bd0 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
25be0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
25bf0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25c00 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
25c10 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
25c20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
25c30 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
25c40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
25c50 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
25c60 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
25c70 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
25c80 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
25c90 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
25ca0 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
25cb0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
25cc0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
25cd0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
25ce0 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
25cf0 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
25d00 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
25d10 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
25d20 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
25d30 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
25d40 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
25d50 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
25d60 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
25d70 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
25d80 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
25d90 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
25da0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
25db0 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
25dc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
25dd0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
25de0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25df0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
25e00 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
25e10 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
25e20 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
25e30 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
25e40 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
25e50 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
25e60 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
25e70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
25e80 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
25e90 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
25ea0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
25eb0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
25ec0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25ed0 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
25ee0 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
25ef0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
25f00 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
25f10 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
25f20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25f30 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
25f40 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
25f50 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
25f60 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
25f70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
25f80 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
25f90 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
25fa0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
25fb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25fc0 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
25fd0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
25fe0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
25ff0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
26000 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
26010 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
26020 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
26030 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
26040 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
26050 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
26060 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
26070 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
26080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26090 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
260a0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
260b0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
260c0 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
260d0 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
260e0 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
260f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
26100 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
26110 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
26120 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
26130 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
26140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26150 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
26160 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
26170 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
26180 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
26190 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
261a0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
261b0 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
261c0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
261d0 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
261e0 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
261f0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
26200 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
26210 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
26220 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
26230 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
26240 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
26250 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
26260 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
26270 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
26280 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
26290 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
262a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
262b0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
262c0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
262d0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
262e0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
262f0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
26300 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
26310 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
26320 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
26330 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
26340 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
26350 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
26360 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
26370 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
26380 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
26390 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
263a0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
263b0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
263c0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
263d0 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
263e0 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
263f0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
26400 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
26410 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
26420 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
26430 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
26440 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
26450 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
26460 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
26470 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
26480 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
26490 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
264a0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
264b0 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
264c0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
264d0 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
264e0 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
264f0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
26500 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
26510 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
26520 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
26530 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
26540 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
26550 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
26560 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
26570 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
26580 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
26590 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
265a0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
265b0 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
265c0 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
265d0 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
265e0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
265f0 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
26600 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
26610 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
26620 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
26630 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
26640 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
26650 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
26660 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
26670 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
26680 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
26690 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
266a0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
266b0 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
266c0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
266d0 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
266e0 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
266f0 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
26700 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
26710 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
26720 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
26730 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
26740 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
26750 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
26760 6e 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  n the third argu
26770 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
26780 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
26790 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
267a0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
267b0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
267c0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
267d0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
267e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
267f0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
26800 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
26810 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
26820 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55  ime option..** U
26830 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
26840 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
26850 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
26860 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
26870 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
26880 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
26890 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
268a0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
268b0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
268c0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
268d0 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
268e0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
268f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
26900 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
26910 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
26920 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
26930 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
26940 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
26950 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
26960 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
26970 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
26980 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
26990 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
269a0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
269b0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
269c0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
269d0 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
269e0 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
269f0 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
26a00 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
26a10 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
26a20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
26a30 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
26a40 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
26a50 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
26a60 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
26a70 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
26a80 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
26a90 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
26aa0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
26ab0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
26ac0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
26ad0 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
26ae0 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
26af0 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
26b00 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
26b10 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
26b20 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
26b30 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
26b40 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
26b50 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
26b60 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
26b70 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
26b80 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
26b90 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f  ve path. .** ^(O
26ba0 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
26bb0 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
26bc0 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
26bd0 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
26be0 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
26bf0 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a  (e.g. "C:").)^.*
26c00 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
26c10 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
26c20 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
26c30 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
26c40 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
26c50 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
26c60 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
26c70 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
26c80 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
26c90 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
26ca0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
26cb0 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
26cc0 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e  and its built-in
26cd0 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72   [VFSes] interpr
26ce0 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  et the.** follow
26cf0 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65  ing query parame
26d00 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
26d10 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
26d20 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
26d30 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
26d40 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
26d50 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
26d60 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
26d70 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
26d80 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
26d90 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
26da0 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
26db0 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
26dc0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
26dd0 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
26de0 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
26df0 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
26e00 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
26e10 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
26e20 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
26e30 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
26e40 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
26e50 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
26e60 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
26e70 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
26e80 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
26e90 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
26ea0 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
26eb0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
26ec0 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
26ed0 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
26ee0 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
26ef0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
26f00 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
26f10 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
26f20 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
26f30 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
26f40 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
26f50 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
26f60 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
26f70 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
26f80 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
26f90 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
26fa0 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
26fb0 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
26fc0 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
26fd0 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
26fe0 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
26ff0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
27000 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
27010 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
27020 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
27030 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
27040 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
27050 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
27060 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
27070 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
27080 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27090 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
270a0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
270b0 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
270c0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
270d0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
270e0 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
270f0 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
27100 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
27110 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
27120 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
27130 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
27140 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
27150 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
27160 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
27170 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
27180 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
27190 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
271a0 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
271b0 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
271c0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
271d0 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
271e0 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
271f0 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
27200 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
27210 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
27220 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
27230 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
27240 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
27250 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
27260 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
27270 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
27280 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
27290 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
272a0 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
272b0 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
272c0 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
272d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
272e0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
272f0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
27300 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
27310 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
27320 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
27330 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
27340 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
27350 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
27360 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
27370 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
27380 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
27390 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
273a0 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
273b0 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
273c0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
273d0 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
273e0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
273f0 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
27400 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
27410 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
27420 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
27430 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
27440 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
27450 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
27460 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
27470 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
27480 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
27490 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
274a0 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
274b0 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
274c0 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
274d0 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
274e0 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
274f0 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
27500 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
27510 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
27520 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
27530 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  g..**.**  <li> <
27540 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65  b>psow</b>: ^The
27550 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20   psow parameter 
27560 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65  indicates whethe
27570 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20  r or not the.** 
27580 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f      [powersafe o
27590 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72  verwrite] proper
275a0 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20  ty does or does 
275b0 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65  not apply to the
275c0 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20  .**     storage 
275d0 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74  media on which t
275e0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
275f0 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20   resides..**.** 
27600 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c   <li> <b>nolock<
27610 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b  /b>: ^The nolock
27620 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
27630 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61  boolean query pa
27640 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77  rameter.**     w
27650 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61  hich if set disa
27660 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e  bles file lockin
27670 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  g in rollback jo
27680 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68  urnal modes.  Th
27690 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65  is.**     is use
276a0 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e  ful for accessin
276b0 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  g a database on 
276c0 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61  a filesystem tha
276d0 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  t does not.**   
276e0 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e    support lockin
276f0 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61  g.  Caution:  Da
27700 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
27710 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  n might result i
27720 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20  f two.**     or 
27730 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77  more processes w
27740 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65  rite to the same
27750 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e   database and an
27760 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a  y one of those.*
27770 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20  *     processes 
27780 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a  uses nolock=1..*
27790 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d  *.**  <li> <b>im
277a0 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68  mutable</b>: ^Th
277b0 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61  e immutable para
277c0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
277d0 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  an query.**     
277e0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
277f0 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
27800 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
27810 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20  is stored on.** 
27820 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65      read-only me
27830 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75  dia.  ^When immu
27840 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51  table is set, SQ
27850 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
27860 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74  t the.**     dat
27870 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f  abase file canno
27880 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76  t be changed, ev
27890 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20  en by a process 
278a0 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20  with higher.**  
278b0 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e     privilege, an
278c0 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73  d so the databas
278d0 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64  e is opened read
278e0 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f  -only and all lo
278f0 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64  cking.**     and
27900 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f   change detectio
27910 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  n is disabled.  
27920 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67  Caution: Setting
27930 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a   the immutable.*
27940 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f  *     property o
27950 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
27960 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66  e that does in f
27970 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72  act change can r
27980 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20  esult.**     in 
27990 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20  incorrect query 
279a0 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b  results and/or [
279b0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20  SQLITE_CORRUPT] 
279c0 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53  errors..**     S
279d0 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
279e0 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
279f0 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20  ]..**       .** 
27a00 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
27a10 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
27a20 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
27a30 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
27a40 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
27a50 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
27a60 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
27a70 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
27a80 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
27a90 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
27aa0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
27ab0 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
27ac0 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
27ad0 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
27ae0 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
27af0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
27b00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
27b10 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
27b20 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
27b30 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
27b40 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
27b50 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
27b60 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
27b70 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
27b80 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
27b90 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
27ba0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
27bb0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
27bc0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
27bd0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
27be0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
27bf0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
27c00 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
27c10 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
27c20 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
27c30 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
27c40 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
27c50 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
27c60 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
27c70 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
27c80 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
27c90 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
27ca0 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
27cb0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27cc0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
27cd0 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
27ce0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
27cf0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
27d00 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
27d10 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
27d20 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
27d30 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
27d40 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
27d50 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
27d60 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
27d70 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
27d80 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
27d90 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
27da0 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
27db0 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
27dc0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
27dd0 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
27de0 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
27df0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
27e00 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
27e10 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
27e20 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
27e30 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
27e40 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
27e50 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
27e60 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
27e70 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
27e80 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
27e90 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
27ea0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
27eb0 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
27ec0 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
27ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
27ee0 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
27ef0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
27f00 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
27f10 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
27f20 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
27f30 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
27f40 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
27f50 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
27f60 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
27f70 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
27f80 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
27f90 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
27fa0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
27fb0 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
27fc0 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20  dotfile <td>.** 
27fd0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
27fe0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
27ff0 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
28000 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
28010 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20  ix-dotfile".**  
28020 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65          that use
28030 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70  s dot-files in p
28040 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64  lace of posix ad
28050 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a  visory locking..
28060 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
28070 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
28080 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
28090 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
280a0 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
280b0 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
280c0 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
280d0 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
280e0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
280f0 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
28100 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
28110 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
28120 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
28130 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
28140 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
28150 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
28160 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
28170 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
28180 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
28190 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
281a0 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
281b0 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
281c0 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
281d0 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
281e0 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
281f0 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
28200 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
28210 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
28220 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
28230 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
28240 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
28250 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
28260 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
28270 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
28280 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
28290 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
282a0 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
282b0 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
282c0 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
282d0 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
282e0 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
282f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
28300 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
28310 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
28320 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
28330 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
28340 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
28350 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
28360 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
28370 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
28380 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
28390 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
283a0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
283b0 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
283c0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
283d0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
283e0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
283f0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
28400 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
28410 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
28420 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
28430 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
28440 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
28450 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  2()..**.** <b>No
28460 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
28470 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
28480 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
28490 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
284a0 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
284b0 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  o calling sqlite
284c0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
284d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
284e0 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
284f0 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
28500 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
28510 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
28520 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
28530 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
28540 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   [sqlite3_temp_d
28550 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74  irectory].*/.int
28560 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
28570 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
28580 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
28590 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
285a0 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
285b0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
285c0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
285d0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
285e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
285f0 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
28600 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
28610 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
28620 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
28630 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
28640 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
28650 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
28660 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
28670 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
28680 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
28690 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
286a0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
286b0 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
286c0 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
286d0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
286e0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
286f0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
28700 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
28710 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
28720 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
28730 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
28740 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
28750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28760 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
28770 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
28780 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
28790 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
287a0 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
287b0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
287c0 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
287d0 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
287e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
287f0 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
28800 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
28810 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
28820 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
28830 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
28840 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
28850 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
28860 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
28870 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
28880 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
28890 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
288a0 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
288b0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
288c0 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
288d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
288e0 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
288f0 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
28900 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
28910 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
28920 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
28930 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
28940 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28950 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28960 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
28970 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
28980 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
28990 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
289a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
289b0 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
289c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
289d0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
289e0 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
289f0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
28a00 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
28a10 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
28a20 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
28a30 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
28a40 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
28a50 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
28a60 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
28a70 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
28a80 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
28a90 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
28aa0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
28ab0 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
28ac0 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
28ad0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
28ae0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
28af0 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
28b00 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
28b10 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
28b20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
28b30 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
28b40 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
28b50 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
28b60 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
28b70 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
28b80 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
28b90 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
28ba0 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
28bb0 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
28bc0 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
28bd0 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
28be0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
28bf0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
28c00 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
28c10 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
28c20 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
28c30 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
28c40 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
28c50 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
28c60 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
28c70 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
28c80 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
28c90 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
28ca0 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
28cb0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
28cc0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
28cd0 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
28ce0 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
28cf0 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
28d00 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
28d10 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
28d20 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
28d30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
28d40 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
28d50 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
28d60 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
28d70 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
28d80 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
28d90 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
28da0 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
28db0 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
28dc0 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
28dd0 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
28de0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
28df0 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
28e00 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
28e10 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
28e20 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
28e30 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
28e40 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
28e50 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
28e60 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
28e70 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
28e80 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
28e90 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
28ea0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
28eb0 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
28ec0 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
28ed0 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
28ee0 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
28ef0 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
28f00 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
28f10 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
28f20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
28f30 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
28f40 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
28f50 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  irable..*/.const
28f60 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
28f70 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
28f80 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
28f90 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
28fa0 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c  zParam);.int sql
28fb0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
28fc0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
28fd0 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
28fe0 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
28ff0 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69  ault);.sqlite3_i
29000 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
29010 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
29020 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
29030 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
29040 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
29050 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
29060 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d  nd Messages.** M
29070 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
29080 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
29090 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33  t recent sqlite3
290a0 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
290b0 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20  ciated with .** 
290c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
290d0 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20  tion] D failed, 
290e0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
290f0 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65  _errcode(D) inte
29100 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
29110 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
29120 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
29130 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29140 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a  ode] for that.**
29150 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66   API call..** If
29160 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
29170 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75   API call was su
29180 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65  ccessful,.** the
29190 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
291a0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
291b0 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
291c0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  efined..** ^The 
291d0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
291e0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
291f0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
29200 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
29210 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
29220 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
29230 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
29240 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
29250 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
29260 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
29270 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29280 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
29290 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
292a0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
292b0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
292c0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
292d0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
292e0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
292f0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
29300 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
29310 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
29320 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
29330 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
29340 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
29350 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
29360 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
29370 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
29380 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
29390 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
293a0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
293b0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
293c0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
293d0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
293e0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
293f0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
29400 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
29410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29420 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
29430 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
29440 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
29450 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
29460 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
29470 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
29480 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
29490 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
294a0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
294b0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
294c0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
294d0 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
294e0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
294f0 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
29500 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
29510 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
29520 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
29530 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
29540 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
29550 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
29560 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
29570 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
29580 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
29590 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
295a0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
295b0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
295c0 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
295d0 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
295e0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
295f0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
29600 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
29610 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
29620 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
29630 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
29640 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
29650 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
29660 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
29670 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
29680 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
29690 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
296a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
296b0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
296c0 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
296d0 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
296e0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
296f0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
29700 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
29710 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
29720 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
29730 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
29740 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
29750 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
29760 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
29770 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
29780 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
29790 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
297a0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
297b0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
297c0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
297d0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
297e0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
297f0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
29800 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
29810 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
29820 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
29830 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
29840 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
29850 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
29860 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
29870 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
29880 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
29890 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
298a0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
298b0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
298c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
298d0 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
298e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
298f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
29900 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
29910 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
29920 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
29930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
29940 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
29950 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
29960 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
29970 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
29980 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20  ent that.** has 
29990 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e  been compiled in
299a0 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61  to binary form a
299b0 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62  nd is ready to b
299c0 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a  e evaluated..**.
299d0 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68  ** Think of each
299e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
299f0 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d  s a separate com
29a00 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20  puter program.  
29a10 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  The.** original 
29a20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72  SQL text is sour
29a30 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70  ce code.  A prep
29a40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
29a50 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65  bject .** is the
29a60 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74   compiled object
29a70 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20   code.  All SQL 
29a80 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
29a90 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70  d into a.** prep
29aa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62  ared statement b
29ab0 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20  efore it can be 
29ac0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  run..**.** The l
29ad0 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70  ife-cycle of a p
29ae0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29af0 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79  t object usually
29b00 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a   goes like this:
29b10 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
29b20 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70  li> Create the p
29b30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29b40 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  t object using [
29b50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29b60 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  v2()]..** <li> B
29b70 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70  ind values to [p
29b80 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
29b90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
29ba0 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
29bb0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
29bc0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
29bd0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
29be0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
29bf0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
29c00 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70  <li> Reset the p
29c10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29c20 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
29c30 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
29c40 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
29c50 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
29c60 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
29c70 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
29c80 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
29c90 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
29ca0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
29cb0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65   </ol>.*/.typede
29cc0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
29cd0 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
29ce0 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
29cf0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
29d00 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  mits.** METHOD: 
29d10 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28  sqlite3.**.** ^(
29d20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
29d30 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
29d40 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
29d50 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
29d60 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
29d70 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
29d80 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
29d90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29da0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
29db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29dc0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
29dd0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
29de0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
29df0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
29e00 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
29e10 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
29e20 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
29e30 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
29e40 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
29e50 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
29e60 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
29e70 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
29e80 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
29e90 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
29ea0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
29eb0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
29ec0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
29ed0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
29ee0 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
29ef0 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
29f00 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
29f10 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
29f20 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
29f30 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
29f40 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
29f50 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
29f60 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
29f70 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
29f80 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
29f90 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
29fa0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
29fb0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
29fc0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
29fd0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
29fe0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
29ff0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
2a000 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
2a010 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
2a020 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
2a030 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
2a040 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
2a050 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
2a060 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
2a070 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
2a080 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
2a090 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
2a0a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
2a0b0 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
2a0c0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
2a0d0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
2a0e0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
2a0f0 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
2a100 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
2a110 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
2a120 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
2a130 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
2a140 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
2a150 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
2a160 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
2a170 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
2a180 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
2a190 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
2a1a0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
2a1b0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
2a1c0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
2a1d0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
2a1e0 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
2a1f0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
2a200 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
2a210 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
2a220 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
2a230 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
2a240 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
2a250 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
2a260 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
2a270 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
2a280 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
2a290 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
2a2a0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
2a2b0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
2a2c0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
2a2d0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
2a2e0 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
2a2f0 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
2a300 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
2a310 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
2a320 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
2a330 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
2a340 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
2a350 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
2a360 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
2a370 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
2a380 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
2a390 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
2a3a0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
2a3b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
2a3c0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
2a3d0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
2a3e0 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
2a3f0 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
2a400 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2a410 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
2a420 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
2a430 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
2a440 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
2a450 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
2a460 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
2a470 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
2a480 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
2a490 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
2a4a0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2a4b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2a4c0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
2a4d0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
2a4e0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
2a4f0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
2a500 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
2a510 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
2a520 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
2a530 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
2a540 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
2a550 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
2a560 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
2a570 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
2a580 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
2a590 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
2a5a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
2a5b0 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
2a5c0 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
2a5d0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
2a5e0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
2a5f0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
2a600 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
2a610 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
2a620 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
2a630 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
2a640 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
2a650 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a660 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
2a670 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2a680 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2a690 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
2a6a0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
2a6b0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
2a6c0 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
2a6d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a6e0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2a6f0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
2a700 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2a710 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2a720 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
2a730 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
2a740 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
2a750 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2a760 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
2a770 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
2a780 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2a790 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
2a7a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a7b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2a7c0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
2a7d0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
2a7e0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2a7f0 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
2a800 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2a810 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
2a820 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
2a830 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
2a840 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
2a850 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a860 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2a870 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
2a880 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2a890 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
2a8a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
2a8b0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
2a8c0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
2a8d0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
2a8e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a8f0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2a900 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
2a910 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2a920 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
2a930 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a940 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
2a950 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
2a960 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
2a970 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a980 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2a990 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
2a9a0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2a9b0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
2a9c0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a9d0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
2a9e0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
2a9f0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
2aa00 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
2aa10 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
2aa20 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65  ent.  If [sqlite
2aa30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2aa40 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61  or.** the equiva
2aa50 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c  lent tries to al
2aa60 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f 72  locate space for
2aa70 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20   more than this 
2aa80 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20  many opcodes.** 
2aa90 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70  in a single prep
2aaa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20  ared statement, 
2aab0 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  an SQLITE_NOMEM 
2aac0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2aad0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
2aae0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
2aaf0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
2ab00 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2ab10 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
2ab20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2ab30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2ab40 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
2ab50 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
2ab60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2ab70 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
2ab80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2ab90 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
2aba0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2abb0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
2abc0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
2abd0 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
2abe0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
2abf0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2ac00 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
2ac10 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
2ac20 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
2ac30 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
2ac40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2ac50 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
2ac60 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
2ac70 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
2ac80 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
2ac90 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
2aca0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2acb0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2acc0 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
2acd0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2ace0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
2acf0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2ad00 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
2ad10 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
2ad20 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
2ad30 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
2ad40 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
2ad50 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
2ad60 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2ad70 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
2ad80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2ad90 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
2ada0 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
2adb0 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
2adc0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2add0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2ade0 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  DS]] ^(<dt>SQLIT
2adf0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
2ae00 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  HREADS</dt>.** <
2ae10 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2ae20 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61  umber of auxilia
2ae30 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64  ry worker thread
2ae40 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a  s that a single.
2ae50 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2ae60 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72  tement] may star
2ae70 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  t.</dd>)^.** </d
2ae80 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
2ae90 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2aea0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2aeb0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
2aec0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
2aed0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
2aee0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2aef0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
2af00 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
2af10 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
2af20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
2af30 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
2af40 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2af50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
2af60 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
2af70 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
2af80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2af90 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
2afa0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
2afb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2afc0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
2afd0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
2afe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2aff0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
2b000 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
2b010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2b020 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2b030 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
2b040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2b050 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2b060 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
2b070 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2b080 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
2b090 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
2b0a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b0b0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
2b0c0 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31  EADS           1
2b0d0 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
2b0e0 46 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67 73  F: Prepare Flags
2b0f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2b100 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
2b110 72 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74  rious flags that
2b120 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 69   can be passed i
2b130 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67  nto.** "prepFlag
2b140 73 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  s" parameter of 
2b150 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
2b160 70 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a  pare_v3()] and.*
2b170 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2b180 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72  re16_v3()] inter
2b190 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  faces..**.** New
2b1a0 20 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64   flags may be ad
2b1b0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
2b1c0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
2b1d0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
2b1e0 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  [[SQLITE_PREPARE
2b1f0 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28  _PERSISTENT]] ^(
2b200 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41  <dt>SQLITE_PREPA
2b210 52 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64  RE_PERSISTENT</d
2b220 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  t>.** <dd>The SQ
2b230 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2b240 53 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20  SISTENT flag is 
2b250 61 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75  a hint to the qu
2b260 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74  ery planner.** t
2b270 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
2b280 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2b290 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  be retained for 
2b2a0 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a  a long time and.
2b2b0 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73  ** probably reus
2b2c0 65 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e  ed many times.)^
2b2d0 20 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20 66   ^Without this f
2b2e0 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  lag, [sqlite3_pr
2b2f0 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61  epare_v3()].** a
2b300 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2b310 61 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75  are16_v3()] assu
2b320 6d 65 20 74 68 61 74 20 74 68 65 20 70 72 65 70  me that the prep
2b330 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77  ared statement w
2b340 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20  ill .** be used 
2b350 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20  just once or at 
2b360 6d 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65 73  most a few times
2b370 20 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f   and then destro
2b380 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  yed using.** [sq
2b390 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2b3a0 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f  ] relatively soo
2b3b0 6e 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20 69  n. The current i
2b3c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63  mplementation ac
2b3d0 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69  ts.** on this hi
2b3e0 6e 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74  nt by avoiding t
2b3f0 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61  he use of [looka
2b400 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20  side memory] so 
2b410 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70  as not to.** dep
2b420 6c 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64  lete the limited
2b430 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73   store of lookas
2b440 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75  ide memory. Futu
2b450 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a  re versions of.*
2b460 2a 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74  * SQLite may act
2b470 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69   on this hint di
2b480 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f  fferently..** </
2b490 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
2b4a0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2b4b0 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20 20  RSISTENT        
2b4c0 20 20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a        0x01../*.*
2b4d0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
2b4e0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
2b4f0 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
2b500 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
2b510 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20  nt compiler}.** 
2b520 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
2b530 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
2b540 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b550 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
2b560 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2b570 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
2b580 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
2b590 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
2b5a0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
2b5b0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2b5c0 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72  s.  Or, in other
2b5d0 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f   words, these ro
2b5e0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f  utines.** are co
2b5f0 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74  nstructors for t
2b600 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b610 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a  tement] object..
2b620 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72  **.** The prefer
2b630 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75  red routine to u
2b640 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70  se is [sqlite3_p
2b650 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54  repare_v2()].  T
2b660 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
2b670 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66  repare()] interf
2b680 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e  ace is legacy an
2b690 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  d should be avoi
2b6a0 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ded..** [sqlite3
2b6b0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68  _prepare_v3()] h
2b6c0 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72 65  as an extra "pre
2b6d0 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74  pFlags" option t
2b6e0 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66  hat is used.** f
2b6f0 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f  or special purpo
2b700 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ses..**.** The u
2b710 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20  se of the UTF-8 
2b720 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70 72  interfaces is pr
2b730 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69  eferred, as SQLi
2b740 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  te currently.** 
2b750 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67  does all parsing
2b760 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54   using UTF-8.  T
2b770 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66  he UTF-16 interf
2b780 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
2b790 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e  d.** as a conven
2b7a0 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d  ience.  The UTF-
2b7b0 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  16 interfaces wo
2b7c0 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67  rk by converting
2b7d0 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65   the.** input te
2b7e0 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74  xt into UTF-8, t
2b7f0 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hen invoking the
2b800 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55   corresponding U
2b810 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a  TF-8 interface..
2b820 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2b830 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
2b840 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
2b850 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
2b860 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
2b870 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
2b880 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b890 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2b8a0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
2b8b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
2b8c0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
2b8d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2b8e0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2b8f0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
2b900 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2b910 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
2b920 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
2b930 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
2b940 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
2b950 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
2b960 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
2b970 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c  3_prepare(), sql
2b980 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b990 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2b9a0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a  3_prepare_v3().*
2b9b0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
2b9c0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
2b9d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c  te3_prepare16(),
2b9e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b9f0 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2ba00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ba10 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d 31  6_v3() use UTF-1
2ba20 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
2ba30 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
2ba40 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2ba50 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
2ba60 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
2ba70 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2ba80 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
2ba90 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
2baa0 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
2bab0 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
2bac0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
2bad0 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
2bae0 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
2baf0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
2bb00 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
2bb10 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
2bb20 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
2bb30 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
2bb40 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
2bb50 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
2bb60 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
2bb70 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
2bb80 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
2bb90 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
2bba0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2bbb0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2bbc0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
2bbd0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
2bbe0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
2bbf0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
2bc00 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
2bc10 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
2bc20 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2bc30 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
2bc40 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
2bc50 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
2bc60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2bc70 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
2bc80 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
2bc90 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
2bca0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
2bcb0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
2bcc0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2bcd0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
2bce0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
2bcf0 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
2bd00 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2bd10 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
2bd20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bd30 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
2bd40 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
2bd50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2bd60 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
2bd70 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
2bd80 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
2bd90 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
2bda0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
2bdb0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
2bdc0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
2bdd0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
2bde0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
2bdf0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
2be00 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
2be10 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
2be20 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
2be30 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
2be40 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
2be50 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
2be60 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2be70 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
2be80 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2be90 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
2bea0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
2beb0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
2bec0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
2bed0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
2bee0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
2bef0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
2bf00 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
2bf10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2bf20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2bf30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2bf40 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74  pare_v2(), sqlit
2bf50 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c  e3_prepare_v3(),
2bf60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2bf70 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2bf80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bf90 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63 65  6_v3() interface
2bfa0 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65  s are recommende
2bfb0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
2bfc0 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f  ograms..** The o
2bfd0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
2bfe0 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  (sqlite3_prepare
2bff0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
2c000 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61  repare16()).** a
2c010 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
2c020 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2c030 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
2c040 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
2c050 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
2c060 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  e "vX" interface
2c070 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
2c080 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
2c090 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
2c0a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2c0b0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
2c0c0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2c0d0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2c0e0 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
2c0f0 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
2c100 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
2c110 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
2c120 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
2c130 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
2c140 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
2c150 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
2c160 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
2c170 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
2c180 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
2c190 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
2c1a0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
2c1b0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2c1c0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
2c1d0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
2c1e0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
2c1f0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
2c200 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
2c210 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
2c220 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
2c230 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
2c240 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
2c250 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
2c260 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
2c270 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
2c280 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2c290 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
2c2a0 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
2c2b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2c2c0 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
2c2d0 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
2c2e0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
2c2f0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2c300 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
2c310 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
2c320 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
2c330 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
2c340 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
2c350 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
2c360 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
2c370 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
2c380 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
2c390 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
2c3a0 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
2c3b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
2c3c0 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
2c3d0 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
2c3e0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
2c3f0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
2c400 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
2c410 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
2c420 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
2c430 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
2c440 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
2c450 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
2c460 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2c470 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2c480 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
2c490 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
2c4a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
2c4b0 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
2c4c0 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
2c4d0 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
2c4e0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2c4f0 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
2c500 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
2c510 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
2c520 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2c530 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
2c540 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
2c550 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
2c560 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
2c570 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c580 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
2c590 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
2c5a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
2c5b0 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
2c5c0 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
2c5d0 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
2c5e0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2c5f0 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
2c600 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
2c610 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2c620 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
2c630 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
2c640 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
2c650 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
2c660 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
2c670 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
2c680 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
2c690 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
2c6a0 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
2c6b0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
2c6c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
2c6d0 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
2c6e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
2c6f0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c   enabled..** </l
2c700 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  i>.** </ol>.**.*
2c710 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72  * <p>^sqlite3_pr
2c720 65 70 61 72 65 5f 76 33 28 29 20 64 69 66 66 65  epare_v3() diffe
2c730 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  rs from sqlite3_
2c740 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c  prepare_v2() onl
2c750 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74  y in having.** t
2c760 68 65 20 65 78 74 72 61 20 70 72 65 70 46 6c 61  he extra prepFla
2c770 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68  gs parameter, wh
2c780 69 63 68 20 69 73 20 61 20 62 69 74 20 61 72 72  ich is a bit arr
2c790 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66  ay consisting of
2c7a0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65   zero or.** more
2c7b0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
2c7c0 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2c7d0 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52  NT|SQLITE_PREPAR
2c7e0 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68  E_*] flags.  ^Th
2c7f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  e.** sqlite3_pre
2c800 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66  pare_v2() interf
2c810 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c  ace works exactl
2c820 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a  y the same as.**
2c830 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c840 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a 65 72  _v3() with a zer
2c850 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61  o prepFlags para
2c860 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  meter..*/.int sq
2c870 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
2c880 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2c890 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2c8a0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2c8b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2c8c0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2c8d0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2c8e0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2c8f0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2c900 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2c910 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2c920 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2c930 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c940 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c950 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2c960 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c970 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2c980 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2c990 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2c9a0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2c9b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c9c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2c9d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2c9e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2c9f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2ca00 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2ca10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2ca20 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2ca30 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2ca40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2ca50 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2ca60 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2ca70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2ca80 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2ca90 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2caa0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2cab0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2cac0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2cad0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2cae0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2caf0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2cb00 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c  repare_v3(.  sql
2cb10 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2cb20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2cb30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2cb40 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2cb50 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2cb60 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2cb70 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2cb80 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2cb90 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2cba0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2cbb0 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67  ytes. */.  unsig
2cbc0 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67  ned int prepFlag
2cbd0 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f  s, /* Zero or mo
2cbe0 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  re SQLITE_PREPAR
2cbf0 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71  E_ flags */.  sq
2cc00 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2cc10 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2cc20 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2cc30 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2cc40 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2cc50 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2cc60 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2cc70 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2cc80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cc90 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2cca0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2ccb0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2ccc0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2ccd0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2cce0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2ccf0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2cd00 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2cd10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2cd20 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2cd30 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2cd40 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2cd50 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2cd60 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2cd70 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2cd80 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2cd90 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2cda0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2cdb0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2cdc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2cdd0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
2cde0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2cdf0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ce00 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2ce10 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2ce20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2ce30 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2ce40 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2ce50 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2ce60 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2ce70 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2ce80 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2ce90 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2cea0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2ceb0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2cec0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2ced0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2cee0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2cef0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2cf00 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2cf10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2cf20 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2cf30 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2cf40 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2cf50 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2cf60 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2cf70 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2cf80 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2cf90 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2cfa0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2cfb0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2cfc0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2cfd0 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69   */.  unsigned i
2cfe0 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a  nt prepFlags, /*
2cff0 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51   Zero or more SQ
2d000 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c  LITE_PREPARE_ fl
2d010 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  ags */.  sqlite3
2d020 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2d030 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2d040 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2d050 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2d060 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2d070 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2d080 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2d090 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2d0a0 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2d0b0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2d0c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2d0d0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2d0e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2d0f0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2d100 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2d110 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2d120 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2d130 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2d140 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d150 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2d160 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b  .** created by [
2d170 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d180 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
2d190 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a  prepare_v3()],.*
2d1a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2d1b0 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
2d1c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d1d0 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  6_v3()]..** ^The
2d1e0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2d1f0 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  d_sql(P) interfa
2d200 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2d210 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a  nter to a UTF-8.
2d220 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
2d230 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78  ning the SQL tex
2d240 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74  t of prepared st
2d250 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a  atement P with.*
2d260 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  * [bound paramet
2d270 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a  ers] expanded..*
2d280 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2d290 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65  le, if a prepare
2d2a0 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
2d2b0 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
2d2c0 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45   SQL.** text "SE
2d2d0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2d2e0 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72  and if parameter
2d2f0 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74   $abc is bound t
2d300 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a  o integer 2345.*
2d310 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * and parameter 
2d320 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c  :xyz is unbound,
2d330 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71   then sqlite3_sq
2d340 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  l() will return.
2d350 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
2d360 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20  string, "SELECT 
2d370 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73  $abc,:xyz" but s
2d380 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2d390 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  sql().** will re
2d3a0 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34  turn "SELECT 234
2d3b0 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a  5,NULL".)^.**.**
2d3c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2d3d0 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74  panded_sql() int
2d3e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e  erface returns N
2d3f0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
2d400 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73  ent memory.** is
2d410 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f   available to ho
2d420 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f  ld the result, o
2d430 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20  r if the result 
2d440 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
2d450 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  .** the maximum 
2d460 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65  string length de
2d470 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2d480 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2d490 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  NGTH]..**.** ^Th
2d4a0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
2d4b0 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
2d4c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2d4d0 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20  limits the size 
2d4e0 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61  of.** bound para
2d4f0 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73  meter expansions
2d500 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
2d510 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70  OMIT_TRACE] comp
2d520 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
2d530 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65  on causes sqlite
2d540 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2d550 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72   to always retur
2d560 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  n NULL..**.** ^T
2d570 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2d580 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71  ed by sqlite3_sq
2d590 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20  l(P) is managed 
2d5a0 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73  by SQLite and is
2d5b0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
2d5c0 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65  y freed when the
2d5d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d5e0 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2d5f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67  ..** ^The string
2d600 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2d610 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2d620 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68  l(P), on the oth
2d630 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f  er hand,.** is o
2d640 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2d650 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2d660 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65  and must be free
2d670 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2d680 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e  ion.** by passin
2d690 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
2d6a0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  _free()]..*/.con
2d6b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2d6c0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2d6d0 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20  t *pStmt);.char 
2d6e0 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  *sqlite3_expande
2d6f0 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  d_sql(sqlite3_st
2d700 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2d710 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2d720 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
2d730 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
2d740 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
2d750 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2d760 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2d770 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2d780 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
2d790 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2d7a0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
2d7b0 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
2d7c0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2d7d0 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
2d7e0 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
2d7f0 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
2d800 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2d810 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
2d820 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
2d830 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2d840 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
2d850 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
2d860 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
2d870 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
2d880 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
2d890 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
2d8a0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2d8b0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
2d8c0 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
2d8d0 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
2d8e0 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
2d8f0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
2d900 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
2d910 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
2d920 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
2d930 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2d940 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
2d950 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
2d960 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2d970 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
2d980 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
2d990 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
2d9a0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
2d9b0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
2d9c0 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
2d9d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
2d9e0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2d9f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
2da00 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
2da10 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2da20 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
2da30 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
2da40 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
2da50 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
2da60 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
2da70 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
2da80 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
2da90 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
2daa0 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
2dab0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2dac0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2dad0 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
2dae0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
2daf0 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
2db00 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
2db10 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
2db20 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
2db30 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
2db40 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
2db50 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
2db60 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
2db70 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
2db80 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
2db90 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
2dba0 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
2dbb0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2dbc0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2dbd0 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
2dbe0 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
2dbf0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
2dc00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
2dc10 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
2dc20 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
2dc30 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
2dc40 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
2dc50 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2dc60 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
2dc70 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2dc80 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2dc90 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2dca0 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45  rns true for [BE
2dcb0 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42  GIN] since.** [B
2dcc0 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74  EGIN] merely set
2dcd0 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73  s internal flags
2dce0 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e  , but the [BEGIN
2dcf0 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45  |BEGIN IMMEDIATE
2dd00 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c  ] and.** [BEGIN|
2dd10 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d  BEGIN EXCLUSIVE]
2dd20 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75   commands do tou
2dd30 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
2dd40 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65  and so.** sqlite
2dd50 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2dd60 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  ) returns false 
2dd70 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e  for those comman
2dd80 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
2dd90 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2dda0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2ddb0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2ddc0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2ddd0 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
2dde0 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
2ddf0 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48  en Reset.** METH
2de00 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2de10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2de20 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2de30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2de40 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2de50 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
2de60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2de70 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
2de80 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
2de90 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
2dea0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
2deb0 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72  ut has neither r
2dec0 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
2ded0 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53   (returned.** [S
2dee0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d  QLITE_DONE] from
2def0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2df00 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20  )]) nor.** been 
2df10 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
2df20 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
2df30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2df40 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
2df50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2df60 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
2df70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
2df80 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
2df90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
2dfa0 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
2dfb0 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
2dfc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dfd0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
2dfe0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2dff0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2e000 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
2e010 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
2e020 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2e030 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
2e040 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
2e050 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
2e060 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
2e070 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e080 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2e090 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
2e0a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2e0b0 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
2e0c0 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
2e0d0 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
2e0e0 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
2e0f0 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
2e100 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
2e110 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
2e120 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
2e130 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
2e140 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
2e150 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e160 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
2e170 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2e180 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
2e190 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
2e1a0 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
2e1b0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
2e1c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e1d0 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
2e1e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
2e1f0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
2e200 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
2e210 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
2e220 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
2e230 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
2e240 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
2e250 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
2e260 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2e270 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
2e280 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
2e290 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
2e2a0 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
2e2b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
2e2c0 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
2e2d0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2e2e0 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
2e2f0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
2e300 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
2e310 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
2e320 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
2e330 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
2e340 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
2e350 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
2e360 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
2e370 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2e380 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
2e390 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
2e3a0 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
2e3b0 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
2e3c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e3d0 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
2e3e0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
2e3f0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
2e400 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
2e410 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
2e420 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
2e430 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
2e440 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2e450 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
2e460 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69  3_value_dup()] i
2e470 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
2e480 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63  used to construc
2e490 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74  t a new .** prot
2e4a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e4b0 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72  lue from an unpr
2e4c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e4d0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
2e4e0 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
2e4f0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
2e500 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
2e510 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
2e520 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
2e530 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
2e540 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
2e550 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
2e560 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e570 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
2e580 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
2e590 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2e5a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e5b0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
2e5c0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
2e5d0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
2e5e0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
2e5f0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
2e600 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
2e610 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
2e620 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
2e630 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
2e640 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
2e650 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
2e660 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
2e670 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
2e680 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
2e690 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
2e6a0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
2e6b0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
2e6c0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
2e6d0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
2e6e0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2e6f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
2e700 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
2e710 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
2e720 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
2e730 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
2e740 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
2e750 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2e760 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
2e770 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
2e780 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
2e790 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
2e7a0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
2e7b0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2e7c0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
2e7d0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
2e7e0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
2e7f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
2e800 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
2e810 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
2e820 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
2e830 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
2e840 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
2e850 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2e860 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
2e870 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
2e880 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2e890 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
2e8a0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2e8b0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2e8c0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
2e8d0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
2e8e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e8f0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
2e900 65 20 75 73 65 64 20 61 73 20 61 72 67 75 6d 65  e used as argume
2e910 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  nts.** to [sqlit
2e920 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2e930 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  )], [sqlite3_bin
2e940 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a  d_value()], and.
2e950 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2e960 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65  e_dup()]..** The
2e970 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e980 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
2e990 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
2e9a0 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
2e9b0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
2e9c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e9d0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
2e9e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2e9f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71  sqlite3_value sq
2ea00 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
2ea10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
2ea20 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
2ea30 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
2ea40 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
2ea50 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
2ea60 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
2ea70 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
2ea80 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2ea90 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
2eaa0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
2eab0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2eac0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
2ead0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
2eae0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
2eaf0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2eb00 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
2eb10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2eb20 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
2eb30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2eb40 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
2eb50 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
2eb60 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
2eb70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2eb80 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
2eb90 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
2eba0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2ebb0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
2ebc0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
2ebd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2ebe0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
2ebf0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
2ec00 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
2ec10 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
2ec20 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
2ec30 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2ec40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2ec50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
2ec60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ec70 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
2ec80 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
2ec90 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
2eca0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
2ecb0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
2ecc0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
2ecd0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
2ece0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
2ecf0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
2ed00 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
2ed10 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
2ed20 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2ed30 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
2ed40 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
2ed50 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
2ed60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
2ed70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
2ed80 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
2ed90 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
2eda0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
2edb0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
2edc0 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
2edd0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
2ede0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
2edf0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
2ee00 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
2ee10 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
2ee20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
2ee30 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
2ee40 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
2ee50 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
2ee60 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
2ee70 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
2ee80 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
2ee90 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
2eea0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
2eeb0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
2eec0 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
2eed0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
2eee0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
2eef0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
2ef00 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
2ef10 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
2ef20 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2ef30 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2ef40 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
2ef50 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2ef60 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
2ef70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2ef80 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
2ef90 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
2efa0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2efb0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
2efc0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
2efd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2efe0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
2eff0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
2f000 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2f010 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2f020 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
2f030 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
2f040 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
2f050 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
2f060 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
2f070 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
2f080 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
2f090 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
2f0a0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
2f0b0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2f0c0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
2f0d0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
2f0e0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
2f0f0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
2f100 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
2f110 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
2f120 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
2f130 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
2f140 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2f150 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2f160 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
2f170 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
2f180 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
2f190 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
2f1a0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
2f1b0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
2f1c0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
2f1d0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
2f1e0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
2f1f0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
2f200 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2f210 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
2f220 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
2f230 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2f240 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
2f250 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
2f260 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
2f270 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2f280 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2f290 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2f2a0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2f2b0 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
2f2c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f2d0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
2f2e0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
2f2f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
2f300 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
2f310 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
2f320 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
2f330 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2f340 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
2f350 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
2f360 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
2f370 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
2f380 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2f390 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2f3a0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
2f3b0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
2f3c0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
2f3d0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
2f3e0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
2f3f0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
2f400 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2f410 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
2f420 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2f430 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2f440 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2f450 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2f460 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
2f470 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
2f480 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
2f490 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
2f4a0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
2f4b0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2f4c0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
2f4d0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2f4e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f4f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2f500 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2f510 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
2f520 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2f530 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
2f540 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
2f550 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
2f560 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2f570 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
2f580 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2f590 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
2f5a0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
2f5b0 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
2f5c0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
2f5d0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
2f5e0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
2f5f0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
2f600 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
2f610 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
2f620 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
2f630 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
2f640 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
2f650 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
2f660 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
2f670 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
2f680 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
2f690 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
2f6a0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
2f6b0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
2f6c0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
2f6d0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
2f6e0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
2f6f0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
2f700 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
2f710 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2f720 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
2f730 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
2f740 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
2f750 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
2f760 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
2f770 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2f780 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2f790 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2f7a0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2f7b0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2f7c0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2f7d0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2f7e0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2f7f0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2f800 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2f810 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
2f820 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
2f830 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
2f840 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
2f850 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
2f860 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
2f870 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2f880 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
2f890 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
2f8a0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
2f8b0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
2f8c0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
2f8d0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2f8e0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
2f8f0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
2f900 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
2f910 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
2f920 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2f930 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
2f940 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
2f950 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
2f960 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2f970 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
2f980 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
2f990 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2f9a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2f9b0 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
2f9c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
2f9d0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
2f9e0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
2f9f0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2fa00 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
2fa10 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
2fa20 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
2fa30 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
2fa40 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
2fa50 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2fa60 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2fa70 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
2fa80 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
2fa90 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
2faa0 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
2fab0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2fac0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
2fad0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
2fae0 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
2faf0 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
2fb00 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
2fb10 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
2fb20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2fb30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2fb40 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
2fb50 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
2fb60 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
2fb70 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
2fb80 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
2fb90 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
2fba0 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
2fbb0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
2fbc0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
2fbd0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
2fbe0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
2fbf0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
2fc00 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
2fc10 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
2fc20 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2fc30 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
2fc40 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
2fc50 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2fc60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2fc70 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2fc80 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2fc90 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2fca0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2fcb0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2fcc0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2fcd0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2fce0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fcf0 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49  bind_pointer(S,I
2fd00 2c 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20  ,P,T,D) routine 
2fd10 63 61 75 73 65 73 20 74 68 65 20 49 2d 74 68 20  causes the I-th 
2fd20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20  parameter in.** 
2fd30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fd40 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61  ent] S to have a
2fd50 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e  n SQL value of N
2fd60 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f  ULL, but to also
2fd70 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   be.** associate
2fd80 64 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74  d with the point
2fd90 65 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20  er P of type T. 
2fda0 20 5e 44 20 69 73 20 65 69 74 68 65 72 20 61 20   ^D is either a 
2fdb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a  NULL pointer or.
2fdc0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
2fdd0 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  a destructor fun
2fde0 63 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51  ction for P. ^SQ
2fdf0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
2fe00 20 74 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74   the.** destruct
2fe10 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67  or D with a sing
2fe20 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50  le argument of P
2fe30 20 77 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69   when it is fini
2fe40 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e  shed using.** P.
2fe50 20 20 54 68 65 20 54 20 70 61 72 61 6d 65 74 65    The T paramete
2fe60 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74  r should be a st
2fe70 61 74 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65  atic string, pre
2fe80 66 65 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67  ferably a string
2fe90 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65  .** literal. The
2fea0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f   sqlite3_bind_po
2feb0 69 6e 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20  inter() routine 
2fec0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  is part of the.*
2fed0 2a 20 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69  * [pointer passi
2fee0 6e 67 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64  ng interface] ad
2fef0 64 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33  ded for SQLite 3
2ff00 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  .20.0..**.** ^If
2ff10 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
2ff20 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2ff30 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2ff40 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
2ff50 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
2ff60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ff70 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
2ff80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ff90 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
2ffa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ffb0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
2ffc0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
2ffd0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
2ffe0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
2fff0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
30000 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
30010 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
30020 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
30030 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
30040 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
30050 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
30060 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
30070 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
30080 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
30090 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
300a0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
300b0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
300c0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
300d0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
300e0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
300f0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
30100 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
30110 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
30120 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
30130 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
30140 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
30150 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
30160 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
30170 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
30180 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54  g..** ^[SQLITE_T
30190 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20  OOBIG] might be 
301a0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
301b0 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67  size of a string
301c0 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65   or BLOB.** exce
301d0 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73  eds limits impos
301e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
301f0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
30200 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a  MIT_LENGTH]) or.
30210 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c  ** [SQLITE_MAX_L
30220 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c  ENGTH]..** ^[SQL
30230 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
30240 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
30250 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
30260 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
30270 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
30280 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
30290 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
302a0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
302b0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
302c0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
302d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
302e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
302f0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
30300 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30310 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
30320 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30330 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
30340 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
30350 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
30360 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
30370 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30380 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
30390 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
303a0 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  t void*, sqlite3
303b0 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
303c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
303d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
303e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
303f0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
30400 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
30410 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
30420 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
30430 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
30440 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
30450 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
30460 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30470 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
30480 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30490 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
304a0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
304b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
304c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
304d0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
304e0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
304f0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
30500 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
30510 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30520 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
30530 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
30540 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
30550 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69  bind_text64(sqli
30560 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
30570 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
30580 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
30590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
305a0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
305b0 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
305c0 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69  har encoding);.i
305d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
305e0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
305f0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
30600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30610 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30620 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65  d_pointer(sqlite
30630 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f  3_stmt*, int, vo
30640 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  id*, const char*
30650 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
30660 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
30670 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
30680 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
30690 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69  int n);.int sqli
306a0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
306b0 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
306c0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
306d0 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  uint64);../*.** 
306e0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
306f0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
30700 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  rs.** METHOD: sq
30710 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30720 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
30730 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
30740 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
30750 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
30760 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
30770 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
30780 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
30790 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
307a0 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
307b0 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
307c0 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
307d0 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
307e0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
307f0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
30800 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
30810 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
30820 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
30830 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
30840 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
30850 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
30860 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
30870 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
30880 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
30890 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
308a0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
308b0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
308c0 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
308d0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
308e0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
308f0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
30900 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
30910 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
30920 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
30930 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
30940 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
30950 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
30960 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
30970 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
30980 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30990 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
309a0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
309b0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
309c0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
309d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
309e0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
309f0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
30a00 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
30a10 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
30a20 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  r.** METHOD: sql
30a30 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30a40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
30a50 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
30a60 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
30a70 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
30a80 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
30a90 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
30aa0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
30ab0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
30ac0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
30ad0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
30ae0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
30af0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
30b00 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
30b10 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
30b20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
30b30 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
30b40 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
30b50 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
30b60 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
30b70 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
30b80 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
30b90 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
30ba0 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
30bb0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
30bc0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
30bd0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
30be0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
30bf0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
30c00 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
30c10 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
30c20 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
30c30 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
30c40 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
30c50 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
30c60 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
30c70 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
30c80 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
30c90 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
30ca0 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
30cb0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
30cc0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
30cd0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
30ce0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
30cf0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
30d00 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
30d10 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
30d20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
30d30 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
30d40 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
30d50 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
30d60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
30d70 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
30d80 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
30d90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
30da0 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a  pare16_v3()]..**
30db0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
30dc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30dd0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
30de0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
30df0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
30e00 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
30e10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30e20 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
30e30 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
30e40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30e50 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
30e60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
30e70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30e80 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
30e90 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
30ea0 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f  en Name.** METHO
30eb0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30ec0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
30ed0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
30ee0 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
30ef0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
30f00 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
30f10 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
30f20 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
30f30 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
30f40 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
30f50 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
30f60 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
30f70 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
30f80 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
30f90 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
30fa0 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
30fb0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
30fc0 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
30fd0 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
30fe0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
30ff0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
31000 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
31010 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
31020 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31030 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  16_v2()] or.** [
31040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
31050 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v3()]..**.** S
31060 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
31070 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
31080 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
31090 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
310a0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
310b0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
310c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
310d0 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  _name()]..*/.int
310e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
310f0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
31100 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
31110 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
31120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31130 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
31140 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
31150 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed Statement.** 
31160 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
31170 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  stmt.**.** ^Cont
31180 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
31190 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
311a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
311b0 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
311c0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
311d0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
311e0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
311f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
31200 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
31210 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
31220 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
31230 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
31240 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
31250 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
31260 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
31270 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
31280 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
31290 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
312a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
312b0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
312c0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
312d0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
312e0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
312f0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
31300 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31310 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75  t]. ^If this rou
31320 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20  tine returns 0, 
31330 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a  that means the .
31340 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
31350 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20  tement] returns 
31360 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  no data (for exa
31370 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
31380 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20  )..** ^However, 
31390 6a 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69  just because thi
313a0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
313b0 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d  s a positive num
313c0 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ber does not.** 
313d0 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72  mean that one or
313e0 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61   more rows of da
313f0 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  ta will be retur
31400 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20  ned.  ^A SELECT 
31410 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c  statement.** wil
31420 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20  l always have a 
31430 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33  positive sqlite3
31440 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20  _column_count() 
31450 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  but depending on
31460 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c   the.** WHERE cl
31470 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
31480 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63   and the table c
31490 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74  ontent, it might
314a0 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e   return no rows.
314b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
314c0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
314d0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
314e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
314f0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
31500 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
31510 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
31520 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
31530 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
31540 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31550 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
31560 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
31570 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
31580 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
31590 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
315a0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
315b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
315c0 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
315d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
315e0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
315f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
31600 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
31610 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
31620 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
31630 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
31640 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31650 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
31660 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
31670 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
31680 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
31690 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
316a0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
316b0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
316c0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
316d0 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
316e0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
316f0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
31700 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
31710 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
31720 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
31730 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
31740 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
31750 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
31760 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31770 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
31780 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
31790 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
317a0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
317b0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
317c0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
317d0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
317e0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
317f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
31800 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
31810 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
31820 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
31830 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
31840 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
31850 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
31860 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
31870 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
31880 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
31890 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
318a0 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
318b0 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
318c0 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
318d0 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
318e0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
318f0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
31900 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
31910 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
31920 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
31930 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
31940 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
31950 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
31960 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
31970 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
31980 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
31990 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
319a0 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
319b0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
319c0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
319d0 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
319e0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
319f0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
31a00 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
31a10 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
31a20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31a30 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
31a40 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
31a50 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31a60 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
31a70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31a80 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
31a90 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
31aa0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
31ab0 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
31ac0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31ad0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
31ae0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
31af0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
31b00 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
31b10 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
31b20 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
31b30 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
31b40 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
31b50 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
31b60 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
31b70 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
31b80 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
31b90 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
31ba0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
31bb0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
31bc0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
31bd0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
31be0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
31bf0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
31c00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
31c10 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
31c20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
31c30 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
31c40 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
31c50 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
31c60 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
31c70 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
31c80 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
31c90 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
31ca0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31cb0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
31cc0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
31cd0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
31ce0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
31cf0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
31d00 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
31d10 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
31d20 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
31d30 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
31d40 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
31d50 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
31d60 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
31d70 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
31d80 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
31d90 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
31da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
31db0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
31dc0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
31dd0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
31de0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
31df0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
31e00 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
31e10 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
31e20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
31e30 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
31e40 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
31e50 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
31e60 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
31e70 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
31e80 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
31e90 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
31ea0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
31eb0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
31ec0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
31ed0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
31ee0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
31ef0 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
31f00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
31f10 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
31f20 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
31f30 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
31f40 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
31f50 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
31f60 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
31f70 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
31f80 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
31f90 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
31fa0 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
31fb0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
31fc0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
31fd0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
31fe0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
31ff0 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
32000 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
32010 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
32020 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
32030 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
32040 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
32050 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
32060 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
32070 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
32080 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
32090 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
320a0 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
320b0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
320c0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
320d0 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
320e0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
320f0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
32100 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
32110 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
32120 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
32130 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
32140 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
32150 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
32160 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
32170 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
32180 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
32190 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
321a0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
321b0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
321c0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
321d0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
321e0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
321f0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
32200 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
32210 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
32220 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
32230 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
32240 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
32250 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
32260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
32270 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
32280 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
32290 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
322a0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
322b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
322c0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
322d0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
322e0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
322f0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
32300 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
32310 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
32320 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
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 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
32350 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
32360 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
32370 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
32380 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
32390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
323a0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
323b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
323c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
323d0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
323e0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
323f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
32400 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
32410 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
32420 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32430 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
32440 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
32450 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
32460 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
32470 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32480 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
32490 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
324a0 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
324b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
324c0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
324d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
324e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
324f0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
32500 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
32510 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
32520 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
32530 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
32540 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
32550 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
32560 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
32570 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
32580 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
32590 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
325a0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
325b0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
325c0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
325d0 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
325e0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
325f0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
32600 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
32610 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
32620 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
32630 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
32640 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
32650 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
32660 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
32670 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
32680 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
32690 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
326a0 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
326b0 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
326c0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
326d0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
326e0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
326f0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
32700 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
32710 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
32720 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
32730 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
32740 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
32750 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
32760 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
32770 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
32780 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
32790 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
327a0 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
327b0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
327c0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
327d0 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
327e0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
327f0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
32800 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
32810 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
32820 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
32830 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
32840 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
32850 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
32860 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
32870 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
32880 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
32890 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
328a0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
328b0 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
328c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
328d0 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
328e0 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
328f0 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
32900 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
32910 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
32920 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
32930 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
32940 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
32950 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
32960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
32970 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
32980 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
32990 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
329a0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
329b0 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
329c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
329d0 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
329e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
329f0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
32a00 65 64 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a  ed using any of.
32a10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
32a20 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
32a30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
32a40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
32a50 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20  are16_v2()],.** 
32a60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
32a70 61 72 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f  are16_v3()] or o
32a80 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
32a90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
32aa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
32ab0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
32ac0 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
32ad0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
32ae0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
32af0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
32b00 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
32b10 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
32b20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
32b30 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
32b40 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
32b50 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
32b60 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
32b70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
32b80 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
32b90 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 58 22  g the newer "vX"
32ba0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b   interfaces.** [
32bb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
32bc0 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v3()], [sqlite3_
32bd0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
32be0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32bf0 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  6_v3()],.** [sql
32c00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
32c10 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
32c20 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
32c30 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
32c40 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
32c50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32c60 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
32c70 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58  f the.** new "vX
32c80 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
32c90 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
32ca0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
32cb0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
32cc0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
32cd0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
32ce0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
32cf0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
32d00 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
32d10 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
32d20 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
32d30 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
32d40 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
32d50 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
32d60 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
32d70 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
32d80 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
32d90 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
32da0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
32db0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
32dc0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
32dd0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
32de0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
32df0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
32e00 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
32e10 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
32e20 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
32e30 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
32e40 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
32e50 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
32e60 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
32e70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
32e80 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
32e90 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
32ea0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
32eb0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
32ec0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
32ed0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
32ee0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
32ef0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
32f00 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
32f10 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
32f20 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
32f30 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
32f40 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
32f50 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
32f60 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
32f70 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
32f80 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
32f90 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
32fa0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
32fb0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
32fc0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
32fd0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
32fe0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
32ff0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
33000 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
33010 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
33020 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
33030 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
33040 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
33050 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
33060 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
33070 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
33080 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
33090 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
330a0 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
330b0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
330c0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
330d0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
330e0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
330f0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
33100 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
33110 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
33120 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
33130 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
33140 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
33150 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
33160 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
33170 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
33180 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
33190 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
331a0 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
331b0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
331c0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
331d0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
331e0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
331f0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
33200 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
33210 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
33220 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
33230 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
33240 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
33250 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
33260 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
33270 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
33280 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
33290 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
332a0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
332b0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
332c0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
332d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
332e0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
332f0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
33300 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
33310 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
33320 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
33330 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
33340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33350 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
33360 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
33370 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
33380 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
33390 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
333a0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
333b0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
333c0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
333d0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
333e0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
333f0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
33400 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
33410 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
33420 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33430 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
33440 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
33450 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33460 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
33470 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
33480 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
33490 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
334a0 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
334b0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
334c0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
334d0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
334e0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
334f0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
33500 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
33510 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
33520 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
33530 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
33540 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
33550 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
33560 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
33570 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
33580 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
33590 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
335a0 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
335b0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
335c0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
335d0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
335e0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
335f0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
33600 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
33610 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
33620 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
33630 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
33640 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
33650 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
33660 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
33670 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
33680 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
33690 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
336a0 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
336b0 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33   [version 3.6.23
336c0 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36  .1] ([dateof:3.6
336d0 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74  .23.1],.** sqlit
336e0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
336f0 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
33700 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
33710 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
33720 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
33730 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
33740 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
33750 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
33760 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
33770 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
33780 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
33790 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
337a0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
337b0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
337c0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
337d0 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
337e0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
337f0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
33800 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
33810 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
33820 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
33830 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
33840 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
33850 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
33860 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
33870 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
33880 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
33890 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
338a0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
338b0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
338c0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
338d0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
338e0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
338f0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
33900 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
33910 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
33920 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
33930 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
33940 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
33950 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
33960 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
33970 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
33980 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
33990 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
339a0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
339b0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
339c0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
339d0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
339e0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
339f0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
33a00 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
33a10 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
33a20 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
33a30 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
33a40 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
33a50 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v3()] or [sql
33a60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33a70 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
33a80 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
33a90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
33aa0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e  epare16_v3()] in
33ab0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
33ac0 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
33ad0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
33ae0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
33af0 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
33b00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
33b10 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
33b20 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
33b30 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
33b40 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
33b50 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
33b60 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66   the "vX" interf
33b70 61 63 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e  aces is recommen
33b80 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
33b90 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
33ba0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
33bb0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
33bc0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
33bd0 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d   result set.** M
33be0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
33bf0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
33c00 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
33c10 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
33c20 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
33c30 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
33c40 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
33c50 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
33c60 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
33c70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
33c80 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
33c90 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
33ca0 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
33cb0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
33cc0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
33cd0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
33ce0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
33cf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
33d00 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
33d10 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
33d20 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
33d30 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
33d40 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
33d50 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
33d60 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
33d70 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
33d80 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
33d90 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
33da0 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
33db0 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
33dc0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
33dd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
33de0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
33df0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
33e00 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
33e10 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
33e20 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
33e30 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
33e40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
33e50 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
33e60 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
33e70 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
33e80 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
33e90 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
33ea0 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
33eb0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
33ec0 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
33ed0 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
33ee0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
33ef0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
33f00 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
33f10 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
33f20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
33f30 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
33f40 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
33f50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
33f60 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
33f70 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
33f80 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
33f90 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
33fa0 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
33fb0 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
33fc0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
33fd0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
33fe0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
33ff0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
34000 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
34010 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
34020 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
34030 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
34040 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
34050 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
34060 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
34070 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
34080 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
34090 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
340a0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
340b0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
340c0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
340d0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
340e0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
340f0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
34100 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
34110 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
34120 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
34130 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
34140 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
34150 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
34160 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
34170 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
34180 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
34190 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
341a0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
341b0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
341c0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
341d0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
341e0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
341f0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
34200 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
34210 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
34220 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
34230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
34240 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
34250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
34260 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
34270 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
34280 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
34290 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
342a0 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
342b0 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  s functions}.** 
342c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
342d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75  stmt.**.** <b>Su
342e0 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62  mmary:</b>.** <b
342f0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65  lockquote><table
34300 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61   border=0 cellpa
34310 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63  dding=0 cellspac
34320 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=0>.** <tr><t
34330 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
34340 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e  umn_blob</b><td>
34350 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72  &rarr;<td>BLOB r
34360 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
34370 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
34380 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64  mn_double</b><td
34390 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20  >&rarr;<td>REAL 
343a0 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
343b0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
343c0 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26  umn_int</b><td>&
343d0 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20  rarr;<td>32-bit 
343e0 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a  INTEGER result.*
343f0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
34400 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
34410 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  4</b><td>&rarr;<
34420 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45  td>64-bit INTEGE
34430 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  R result.** <tr>
34440 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
34450 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74  olumn_text</b><t
34460 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d  d>&rarr;<td>UTF-
34470 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a  8 TEXT result.**
34480 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
34490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
344a0 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  6</b><td>&rarr;<
344b0 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72  td>UTF-16 TEXT r
344c0 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
344d0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
344e0 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e  mn_value</b><td>
344f0 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65  &rarr;<td>The re
34500 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b  sult as an .** [
34510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e  sqlite3_value|un
34520 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
34530 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
34540 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73  .** <tr><td>&nbs
34550 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e  p;<td>&nbsp;<td>
34560 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74  &nbsp;.** <tr><t
34570 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
34580 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64  umn_bytes</b><td
34590 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20  >&rarr;<td>Size 
345a0 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20  of a BLOB.** or 
345b0 61 20 55 54 46 2d 38 20 54 45 58 54 20 72 65 73  a UTF-8 TEXT res
345c0 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20  ult in bytes.** 
345d0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
345e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
345f0 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62  6&nbsp;&nbsp;</b
34600 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26  >.** <td>&rarr;&
34610 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53  nbsp;&nbsp;<td>S
34620 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a  ize of UTF-16.**
34630 20 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a   TEXT in bytes.*
34640 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
34650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
34660 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
34670 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74  d>Default.** dat
34680 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73  atype of the res
34690 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c  ult.** </table><
346a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
346b0 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f  ** <b>Details:</
346c0 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  b>.**.** ^These 
346d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
346e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
346f0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
34700 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
34710 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
34720 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
34730 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
34740 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
34750 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
34760 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
34770 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
34780 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
34790 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
347a0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
347b0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
347c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
347d0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
347e0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
347f0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
34800 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
34810 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
34820 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
34830 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
34840 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
34850 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
34860 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
34870 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
34880 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
34890 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
348a0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
348b0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
348c0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
348d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
348e0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
348f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
34900 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
34910 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
34920 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
34930 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
34940 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
34950 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
34960 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
34970 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
34980 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
34990 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
349a0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
349b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
349c0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
349d0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
349e0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
349f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
34a00 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
34a10 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
34a20 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
34a30 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
34a40 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
34a50 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
34a60 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
34a70 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
34a80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34a90 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
34aa0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
34ab0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
34ac0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
34ad0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
34ae0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
34af0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
34b00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
34b10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
34b20 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
34b30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
34b40 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
34b50 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
34b60 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
34b70 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
34b80 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
34b90 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
34ba0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
34bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
34bc0 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 73 20   six interfaces 
34bd0 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c  (_blob, _double,
34be0 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f   _int, _int64, _
34bf0 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31  text, and _text1
34c00 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72  6).** each retur
34c10 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61  n the value of a
34c20 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
34c30 6e 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74  n a specific dat
34c40 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a  a format.  If.**
34c50 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
34c60 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61  mn is not initia
34c70 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75 65  lly in the reque
34c80 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72  sted format (for
34c90 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20   example,.** if 
34ca0 74 68 65 20 71 75 65 72 79 20 72 65 74 75 72 6e  the query return
34cb0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74  s an integer but
34cc0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
34cd0 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72  umn_text() inter
34ce0 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20  face.** is used 
34cf0 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 76  to extract the v
34d00 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75  alue) then an au
34d10 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e  tomatic type con
34d20 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
34d30 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rmed..**.** ^The
34d40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34d50 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
34d60 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
34d70 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
34d80 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
34d90 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
34da0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
34db0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
34dc0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
34dd0 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
34de0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
34df0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
34e00 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
34e10 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
34e20 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
34e30 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74  ULL]..** The ret
34e40 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c  urn value of sql
34e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
34e60 28 29 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  () can be used t
34e70 6f 20 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a  o decide which.*
34e80 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 73  * of the first s
34e90 69 78 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  ix interface sho
34ea0 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20 65  uld be used to e
34eb0 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d  xtract the colum
34ec0 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20  n value..** The 
34ed0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
34ee0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
34ef0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
34f00 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
34f10 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79  .** automatic ty
34f20 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  pe conversions h
34f30 61 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72  ave occurred for
34f40 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75   the value in qu
34f50 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74  estion.  .** Aft
34f60 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
34f70 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74  sion, the result
34f80 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   of calling sqli
34f90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34fa0 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  ).** is undefine
34fb0 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65  d, though harmle
34fc0 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ss.  Future.** v
34fd0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
34fe0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
34ff0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
35000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
35010 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
35020 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
35030 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
35040 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
35050 20 6f 72 20 61 20 54 45 58 54 20 73 74 72 69 6e   or a TEXT strin
35060 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  g, then the sqli
35070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35080 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
35090 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
350a0 29 20 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e  ) interfaces can
350b0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 74 65   be used to dete
350c0 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a  rmine the size.*
350d0 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f  * of that BLOB o
350e0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  r string..**.** 
350f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
35100 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
35110 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
35120 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
35130 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
35140 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
35150 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
35160 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
35170 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
35180 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
35190 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
351a0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
351b0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
351c0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
351d0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
351e0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
351f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
35200 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
35210 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
35220 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
35230 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35240 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
35250 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
35260 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
35270 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
35280 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
35290 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
352a0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
352b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
352c0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
352d0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
352e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
352f0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
35300 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
35310 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
35320 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
35330 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
35340 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
35350 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35360 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
35370 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
35380 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
35390 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
353a0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
353b0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
353c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
353d0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
353e0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
353f0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
35400 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
35410 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
35420 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
35430 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
35440 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
35450 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
35460 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
35470 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
35480 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
35490 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
354a0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
354b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
354c0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
354d0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
354e0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
354f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
35500 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
35510 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
35520 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
35530 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
35540 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
35550 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
35560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35570 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
35580 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
35590 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
355a0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
355b0 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
355c0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
355d0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
355e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
355f0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
35600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35610 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
35620 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
35630 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
35640 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
35650 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
35660 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
35670 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
35680 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35690 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
356a0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
356b0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
356c0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
356d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
356e0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
356f0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
35700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
35710 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
35720 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
35730 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
35740 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62  * <b>Warning:</b
35750 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  > ^The object re
35760 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
35770 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
35780 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
35790 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
357a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
357b0 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61   In a multithrea
357c0 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c  ded environment,
357d0 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  .** an unprotect
357e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
357f0 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79   object may only
35800 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20   be used safely 
35810 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
35820 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
35830 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
35840 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
35850 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
35860 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35870 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
35880 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
35890 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
358a0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
358b0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
358c0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
358d0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
358e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
358f0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
35900 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
35910 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
35920 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
35930 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f  e behavior is no
35940 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a  t threadsafe..**
35950 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69   Hence, the sqli
35960 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
35970 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
35980 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79  is normally only
35990 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74   useful within t
359a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
359b0 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63  n of .** [applic
359c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
359d0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20  L functions] or 
359e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
359f0 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20  , not within.** 
35a00 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63  top-level applic
35a10 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  ation code..**.*
35a20 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f 75 74  * The these rout
35a30 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74  ines may attempt
35a40 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
35a50 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20  datatype of the 
35a60 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20  result..** ^For 
35a70 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
35a80 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
35a90 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
35aa0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
35ab0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
35ac0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
35ad0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
35ae0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
35af0 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
35b00 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
35b10 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
35b20 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
35b30 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
35b40 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
35b50 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
35b60 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
35b70 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
35b80 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
35b90 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
35ba0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
35bb0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
35bc0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
35bd0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
35be0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
35bf0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
35c00 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
35c10 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
35c20 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
35c30 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
35c40 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
35c50 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
35c60 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
35c70 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
35c80 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
35c90 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
35ca0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
35cb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
35cc0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
35cd0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
35ce0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
35cf0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
35d00 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
35d10 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
35d20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
35d30 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
35d40 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
35d50 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
35d60 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
35d70 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
35d80 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
35d90 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
35da0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
35db0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
35dc0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
35dd0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
35de0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
35df0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
35e00 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
35e10 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
35e20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
35e30 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42  <td> [CAST] to B
35e40 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  LOB.** <tr><td> 
35e50 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
35e60 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
35e70 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
35e80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
35e90 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
35ea0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35eb0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
35ec0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
35ed0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35ee0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
35ef0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
35f00 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
35f10 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
35f20 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
35f30 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
35f40 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
35f50 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
35f60 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
35f70 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
35f80 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
35f90 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
35fa0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
35fb0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
35fc0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  e>)^.**.** Note 
35fd0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
35fe0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
35ff0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
36000 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
36010 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
36020 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
36030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36040 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
36050 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36060 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
36070 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
36080 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
36090 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
360a0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
360b0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
360c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
360d0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
360e0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
360f0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
36100 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
36110 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
36120 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
36130 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
36140 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
36150 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
36160 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
36170 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
36180 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
36190 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
361a0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
361b0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
361c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
361d0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
361e0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
361f0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
36200 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
36210 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
36220 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
36230 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
36240 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
36250 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
36260 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
36270 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36280 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
36290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
362a0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
362b0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
362c0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
362d0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
362e0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
362f0 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
36300 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
36310 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
36320 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
36330 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
36340 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
36350 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
36360 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
36370 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
36380 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
36390 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
363a0 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
363b0 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
363c0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
363d0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
363e0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
363f0 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
36400 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
36410 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
36420 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
36430 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
36440 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
36450 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
36460 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
36470 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63  The safest polic
36480 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
36490 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
364a0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
364b0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
364c0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
364d0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
364e0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
364f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
36500 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
36510 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
36520 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
36530 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
36540 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36550 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
36560 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36570 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
36580 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
36590 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
365a0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
365b0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
365c0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
365d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
365e0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
365f0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
36600 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
36610 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
36620 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
36630 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
36640 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
36650 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
36660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36670 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
36680 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
36690 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
366a0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
366b0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
366c0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
366d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
366e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
366f0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
36700 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
36710 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
36720 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
36730 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
36740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36750 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
36760 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
36770 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
36780 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
36790 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
367a0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
367b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
367c0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
367d0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
367e0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
367f0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
36800 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
36810 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
36820 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
36830 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
36840 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
36850 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
36860 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
36870 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
36880 20 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f   not pass the po
36890 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
368a0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
368b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
368c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
368d0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
368e0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
368f0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
36900 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
36910 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
36920 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
36930 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
36940 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
36950 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
36960 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
36970 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
36980 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
36990 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
369a0 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
369b0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
369c0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
369d0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
369e0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
369f0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
36a00 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
36a10 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
36a20 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
36a30 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
36a40 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
36a50 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36a60 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
36a70 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
36a80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36a90 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
36aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
36ab0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36ac0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
36ad0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
36ae0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
36af0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36b00 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
36b10 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
36b20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
36b30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36b40 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
36b50 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
36b60 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
36b70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36b80 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
36b90 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
36ba0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
36bb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36bc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
36bd0 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
36be0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36bf0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
36c00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
36c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36c20 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
36c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
36c40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
36c50 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
36c60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
36c70 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
36c80 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
36c90 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20  .** DESTRUCTOR: 
36ca0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
36cb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36cc0 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
36cd0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
36ce0 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
36cf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
36d00 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
36d10 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
36d20 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
36d30 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
36d40 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
36d50 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
36d60 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
36d70 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
36d80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
36d90 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
36da0 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
36db0 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
36dc0 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
36dd0 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
36de0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
36df0 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
36e00 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
36e10 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
36e20 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
36e30 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
36e40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
36e50 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
36e60 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
36e70 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
36e80 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
36e90 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
36ea0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36eb0 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
36ec0 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
36ed0 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
36ee0 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
36ef0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
36f00 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
36f10 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
36f20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
36f30 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
36f40 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
36f50 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
36f60 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
36f70 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
36f80 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
36f90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
36fa0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
36fb0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
36fc0 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
36fd0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
36fe0 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
36ff0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
37000 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
37010 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
37020 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
37030 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
37040 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
37050 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
37060 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
37070 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
37080 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
37090 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
370a0 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
370b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
370c0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
370d0 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
370e0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
370f0 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
37100 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
37110 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
37120 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
37130 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
37140 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
37150 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
37160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37170 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
37180 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
37190 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ject.** METHOD: 
371a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
371b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
371c0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
371d0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
371e0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
371f0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
37200 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
37210 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
37220 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
37230 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
37240 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
37250 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
37260 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
37270 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
37280 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
37290 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
372a0 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
372b0 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
372c0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
372d0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
372e0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
372f0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
37300 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
37310 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
37320 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
37330 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37340 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
37350 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
37360 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
37370 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
37380 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
37390 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
373a0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
373b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
373c0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
373d0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
373e0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
373f0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
37400 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
37410 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
37420 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
37430 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
37440 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
37450 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
37460 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
37470 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
37480 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
37490 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
374a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
374b0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
374c0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
374d0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
374e0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
374f0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
37500 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
37510 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
37520 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
37530 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
37540 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
37550 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
37560 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
37570 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
37580 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
37590 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
375a0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
375b0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
375c0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
375d0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
375e0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
375f0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
37600 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
37610 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
37620 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
37630 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
37640 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
37650 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
37660 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
37670 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
37680 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
37690 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
376a0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
376b0 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
376c0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
376d0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
376e0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
376f0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
37700 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
37710 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
37720 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
37730 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
37740 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
37750 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
37760 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
37770 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
37780 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
37790 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
377a0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
377b0 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
377c0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
377d0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
377e0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
377f0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
37800 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
37810 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
37820 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
37830 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
37840 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
37850 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
37860 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37870 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
37880 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
37890 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
378a0 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
378b0 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
378c0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
378d0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
378e0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
378f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
37900 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
37910 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
37920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37930 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
37940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
37950 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
37960 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
37970 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
37980 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
37990 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
379a0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
379b0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
379c0 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
379d0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
379e0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
379f0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
37a00 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
37a10 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
37a20 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
37a30 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
37a40 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
37a50 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
37a60 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
37a70 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
37a80 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
37a90 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
37aa0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
37ab0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
37ac0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
37ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
37ae0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
37af0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
37b00 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
37b10 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
37b20 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
37b30 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
37b40 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
37b50 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
37b60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
37b70 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
37b80 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
37b90 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
37ba0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
37bb0 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
37bc0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
37bd0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
37be0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
37bf0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
37c00 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
37c10 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
37c20 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
37c30 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
37c40 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
37c50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
37c60 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
37c70 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
37c80 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
37c90 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
37ca0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
37cb0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
37cc0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
37cd0 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
37ce0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
37cf0 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
37d00 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
37d10 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
37d20 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
37d30 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
37d40 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
37d50 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
37d60 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
37d70 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
37d80 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
37d90 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
37da0 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
37db0 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
37dc0 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
37dd0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
37de0 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
37df0 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
37e00 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
37e10 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
37e20 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
37e30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
37e40 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
37e50 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
37e60 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
37e70 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
37e80 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
37e90 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
37ea0 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
37eb0 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
37ec0 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
37ed0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
37ee0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
37ef0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
37f00 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
37f10 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
37f20 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
37f30 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
37f40 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
37f50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
37f60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
37f70 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
37f80 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
37f90 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
37fa0 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
37fb0 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
37fc0 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
37fd0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
37fe0 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
37ff0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
38000 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
38010 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
38020 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
38030 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
38040 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
38050 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
38060 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
38070 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
38080 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
38090 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
380a0 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
380b0 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
380c0 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
380d0 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
380e0 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
380f0 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
38100 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
38110 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
38120 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
38130 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
38140 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
38150 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
38160 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
38170 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
38180 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
38190 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
381a0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
381b0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
381c0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
381d0 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
381e0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
381f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
38200 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
38210 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
38220 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
38230 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
38240 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
38250 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
38260 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
38270 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
38280 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
38290 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
382a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
382b0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
382c0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
382d0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
382e0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
382f0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
38300 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
38310 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
38320 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
38330 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
38340 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
38350 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
38360 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
38370 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
38380 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
38390 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
383a0 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
383b0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
383c0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
383d0 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
383e0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
383f0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
38400 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
38410 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
38420 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
38430 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
38440 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
38450 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
38460 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
38470 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
38480 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
38490 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
384a0 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
384b0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
384c0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
384d0 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
384e0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
384f0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
38500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38510 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
38520 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
38530 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
38540 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
38550 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
38560 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
38570 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
38580 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
38590 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
385a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
385b0 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
385c0 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
385d0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
385e0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
385f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
38600 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
38610 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
38620 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
38630 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
38640 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
38650 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
38660 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
38670 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
38680 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
38690 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
386a0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
386b0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
386c0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
386d0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
386e0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
386f0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
38700 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
38710 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
38720 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
38730 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
38740 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
38750 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
38760 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
38770 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
38780 41 20 66 75 6e