/ Hex Artifact Content
Login

Artifact 5a2d431493020c2c9f2f37c9119d6439444e3c44a714566a5192b6911ac917e6:


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 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5bc0: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28  DIRTYWAL       (
5bd0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5be0: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74  | (5<<8)) /* Not
5bf0: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   Used */.#define
5c00: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5c10: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5c20: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5c30: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5c40: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5c50: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20  _SEQUENCE       
5c60: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5c70: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5c90: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5ca0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5cb0: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5cc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5cd0: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5ce0: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5cf0: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5d00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5d10: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
5d20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5d30: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
5d40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d50: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5d60: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5d70: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5d80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d90: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49  E_READONLY_CANTI
5da0: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54  NIT       (SQLIT
5db0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c  E_READONLY | (5<
5dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dd0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52  ITE_READONLY_DIR
5de0: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c  ECTORY      (SQL
5df0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5e00: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5e10: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5e20: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5e30: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5e60: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5e70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5e80: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5e90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5ea0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5eb0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ec0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ee0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5ef0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5f00: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5f10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5f20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5f30: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5f40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5f50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5f60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5f70: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5f80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5f90: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5fa0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5fb0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5fc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5fd0: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
5fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ff0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
6000: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
6010: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
6020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6030: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
6040: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
6050: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
6060: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6070: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6080: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
6090: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
60a0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
60b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
60c0: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
60d0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
60e0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
60f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
6100: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
6110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
6120: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
6130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
6140: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
6150: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
6160: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
6170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6180: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
6190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
61a0: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
61b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
61c0: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
61d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
61e0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
6200: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
6210: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
6220: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
6230: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
6240: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
6250: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
6260: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
6270: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6280: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6290: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
62a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
62b0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
62c0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
62d0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
62e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
62f0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
6300: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6310: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
6320: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6330: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
6340: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6350: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6360: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6370: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6380: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6390: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
63d0: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
6410: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
6420: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
6430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6440: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
6450: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6460: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6470: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6480: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6490: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
64a0: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
64b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64c0: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
64d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
64e0: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
64f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6510: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
6520: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6530: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
6540: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6590: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65a0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
65b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
65c0: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
65d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65e0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
65f0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
6600: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
6610: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6620: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
6630: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
6640: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
6650: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6660: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6670: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6680: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6690: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66a0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
66b0: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
66c0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
66d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66e0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
66f0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
6700: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6710: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6720: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
6730: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
6740: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6750: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6760: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6770: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6780: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6790: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
67d0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
6820: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6870: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6880: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6890: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
68a0: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
68b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
68c0: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
68d0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
68e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
68f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
6900: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6910: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
6920: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6930: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
6940: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
6950: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6960: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6970: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6980: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6990: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
69a0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
69b0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
69c0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
69d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
69e0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
69f0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6a00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a10: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6a20: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6a30: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6a40: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6a50: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6a60: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6a70: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6a80: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6a90: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6aa0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6ab0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6ac0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6ad0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6ae0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6af0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6b00: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6b10: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6b20: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6b30: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6b40: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6b50: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6b60: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6b70: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6b80: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6b90: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6ba0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6bb0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6bc0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6bd0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6be0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6bf0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6c00: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6c10: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6c20: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6c30: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6c40: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6c50: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6c60: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6c70: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6c80: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6c90: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6ca0: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6cb0: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6cc0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6cd0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6ce0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6cf0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6d00: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6d10: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6d20: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6d30: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6d40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6d50: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6d60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6d70: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6d80: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6d90: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
6da0: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6db0: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6dc0: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6dd0: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6de0: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6df0: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6e00: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6e10: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6e20: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6e30: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6e40: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
6e50: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  leges..**.** The
6e60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6e70: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  TCH_ATOMIC prope
6e80: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74  rty means that t
6e90: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
6ea0: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70   filesystem supp
6eb0: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69  orts doing multi
6ec0: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74  ple write operat
6ed0: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20  ions atomically 
6ee0: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72  when those.** wr
6ef0: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
6f00: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20  re bracketed by 
6f10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
6f20: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
6f30: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
6f40: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
6f50: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a  OMIC_WRITE]..*/.
6f60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6f70: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6f80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6f90: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6fa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6fb0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6fc0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6fd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6fe0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
6ff0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7000: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
7010: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7020: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
7030: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
7040: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7050: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
7060: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7070: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7080: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
70a0: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
70b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
70c0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
70d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
70e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
70f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
7100: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7110: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
7120: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7130: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
7140: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
7150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7160: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7170: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7180: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7190: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
71a0: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
71b0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
71c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
71d0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
71e0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
71f0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
7200: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
7210: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
7220: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
7230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7240: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
7250: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
7260: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7270: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
7280: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78  MIC           0x
7290: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
72a0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
72b0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
72c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
72d0: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
72e0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
72f0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
7300: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
7310: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
7320: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7330: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
7340: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
7350: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7360: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
7370: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
7380: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
7390: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
73a0: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
73b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
73c0: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
73d0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
73e0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
73f0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
7400: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7410: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
7420: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
7430: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
7440: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
7450: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
7460: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
7470: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
7480: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7490: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
74a0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
74b0: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
74c0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
74d0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
74e0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
74f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7500: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
7510: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
7520: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
7530: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
7540: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
7550: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
7560: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
7570: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
7580: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
7590: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
75a0: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
75b0: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
75c0: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
75d0: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
75e0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
75f0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
7600: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
7610: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
7620: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
7630: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
7640: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7650: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
7660: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7670: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7680: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7690: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
76a0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
76b0: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
76c0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
76d0: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
76e0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
76f0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
7700: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
7710: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
7720: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
7730: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
7740: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
7750: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7760: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7770: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7780: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7790: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
77a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
77b0: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
77c0: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
77d0: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
77e0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
77f0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
7800: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
7810: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
7820: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
7830: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
7840: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
7850: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7860: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7870: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7880: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7890: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
78a0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
78b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
78c0: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
78d0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
78e0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
78f0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
7900: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
7910: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
7920: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
7930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7940: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
7950: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7960: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7970: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7980: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7990: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
79a0: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
79b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
79c0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
79d0: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
79e0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
79f0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7a00: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7a10: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
7a20: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
7a30: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7a40: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7a50: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7a60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7a70: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7a80: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7a90: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7aa0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7ab0: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7ac0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7ad0: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7ae0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7af0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7b00: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7b10: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7b20: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7b30: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7b40: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7b50: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7b60: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7b70: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7b80: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7b90: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7ba0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7bb0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7bc0: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7bd0: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7be0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7bf0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7c00: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7c10: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7c20: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7c30: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7c40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7c50: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7c60: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7c70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7c80: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7c90: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7ca0: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7cc0: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7cd0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7ce0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7cf0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7d00: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7d10: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7d20: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7d30: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7d40: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7d50: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7d60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7d70: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7d80: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7d90: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7da0: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7db0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7dc0: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7dd0: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7de0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7df0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7e00: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7e10: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7e20: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7e30: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7e40: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7e50: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7e60: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7e70: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7e80: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7e90: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7ea0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7eb0: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7ec0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7ed0: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7ee0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7ef0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7f00: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7f10: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7f20: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7f30: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7f40: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7f50: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7f60: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7f70: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7f80: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7f90: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7fa0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7fb0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7fc0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7fd0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
7fe0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
7ff0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
8000: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
8010: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
8020: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
8030: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
8040: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
8050: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
8060: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
8070: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
8080: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
8090: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
80a0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
80b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
80c0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
80d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
80e0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
80f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8100: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
8110: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8120: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
8130: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
8140: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
8150: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
8160: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
8170: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
8180: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
8190: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
81a0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
81b0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
81c0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
81d0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
81e0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
81f0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
8200: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
8210: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
8220: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
8230: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
8240: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
8250: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
8260: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
8270: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
8280: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
8290: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
82a0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
82b0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
82c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
82d0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
82e0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
82f0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
8300: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8310: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
8320: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
8330: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
8340: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
8350: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
8360: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
8370: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
8380: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
8390: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
83a0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
83b0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
83c0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
83d0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
83e0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
83f0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
8400: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
8410: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
8420: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
8430: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
8440: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
8450: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
8460: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
8470: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
8480: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
8490: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
84a0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
84b0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
84c0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
84d0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
84e0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
84f0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
8500: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
8510: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
8520: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
8530: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
8540: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
8550: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
8560: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
8570: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
8580: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
8590: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
85a0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
85b0: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
85c0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
85d0: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
85e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
85f0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
8600: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
8610: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
8620: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
8630: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
8640: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
8650: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
8660: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
8670: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8680: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8690: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
86a0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
86b0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
86c0: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
86d0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
86e0: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
86f0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
8700: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
8710: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
8720: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8730: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
8740: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
8750: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
8760: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
8770: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8780: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8790: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
87a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
87b0: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
87c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
87d0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
87e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
87f0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
8800: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8810: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
8820: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8830: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8840: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8850: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
8860: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8870: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8880: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8890: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
88a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
88b0: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
88c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
88d0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
88e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
88f0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
8900: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8910: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
8920: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e  EN_OPEN].** <li>
8930: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
8940: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
8950: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  TE].** <li> [SQL
8960: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
8970: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BLE].** <li> [SQ
8980: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
8990: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c  _ATOMIC].** </ul
89a0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
89b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
89c0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
89d0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
89e0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
89f0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8a00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8a10: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
8a20: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
8a30: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
8a40: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8a50: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8a60: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8a70: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8a80: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8a90: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8aa0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8ab0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8ac0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8ad0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8ae0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8af0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8b00: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8b10: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8b20: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8b30: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8b40: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8b50: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8b60: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8b70: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8b80: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8b90: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8ba0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8bb0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8bc0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8bd0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8be0: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8bf0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8c00: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8c10: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8c20: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8c30: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8c40: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8c50: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8c60: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8c70: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8c80: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8c90: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8ca0: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8cb0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8cc0: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8cd0: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8ce0: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8cf0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8d00: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8d10: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8d20: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8d30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8d40: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8d50: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8d60: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8d70: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8d80: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8d90: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8da0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8db0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8dc0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8dd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8de0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8df0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8e00: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8e10: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8e20: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8e30: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8e40: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8e50: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8e60: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8e70: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8e80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8e90: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8ea0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8eb0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8ec0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8ed0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8ee0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8ef0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8f00: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8f10: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8f20: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8f30: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8f40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8f50: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8f60: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8f70: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8f80: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8f90: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8fa0: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8fb0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8fc0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8fd0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8fe0: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
8ff0: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
9000: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
9010: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
9020: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
9030: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
9040: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
9050: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
9060: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
9070: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
9080: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
9090: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
90a0: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
90b0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
90c0: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
90d0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
90e0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
90f0: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
9100: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
9110: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
9120: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
9130: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
9140: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
9150: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
9160: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9170: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
9180: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9190: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
91a0: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
91b0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
91c0: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
91d0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
91e0: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
91f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
9200: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
9210: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
9220: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
9230: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
9240: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
9250: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
9260: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
9270: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
9280: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
9290: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
92a0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
92b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
92c0: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
92d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
92e0: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
92f0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
9300: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9310: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
9320: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9330: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
9340: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9350: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
9360: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9370: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
9380: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
9390: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
93a0: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
93b0: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
93c0: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
93d0: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
93e0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
93f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
9400: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
9410: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
9420: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
9430: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
9440: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
9450: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
9460: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9470: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9480: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9490: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
94a0: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
94b0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
94c0: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
94d0: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
94e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
94f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9500: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
9510: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
9520: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
9530: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
9540: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
9550: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9560: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9570: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9580: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9590: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
95a0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
95b0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
95c0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
95d0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
95e0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
95f0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
9600: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
9610: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
9620: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
9630: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
9640: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
9650: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9660: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9670: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9680: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9690: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
96a0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
96b0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
96c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
96d0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
96e0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
96f0: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
9700: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
9710: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
9720: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
9730: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
9740: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
9750: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
9760: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
9770: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9780: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
9790: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
97a0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
97b0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
97c0: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
97d0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
97e0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
97f0: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
9800: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
9810: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
9820: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
9830: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
9840: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
9850: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
9860: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
9870: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
9880: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
9890: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
98a0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
98b0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
98c0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
98d0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
98e0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
98f0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9900: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9910: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9920: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
9930: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
9940: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
9950: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
9960: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9970: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9980: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9990: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
99a0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
99b0: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
99c0: 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  L_POINTER] opcod
99d0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
99e0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
99f0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9a00: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9a10: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
9a20: 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28  e journal file (
9a30: 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72  either.** the [r
9a40: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d  ollback journal]
9a50: 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61   or the [write-a
9a60: 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61  head log]) for a
9a70: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9a80: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9a90: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9aa0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9ab0: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9ac0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9ad0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9ae0: 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  ]].** No longer 
9af0: 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  in use..**.** <l
9b00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b10: 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SYNC]].** The [
9b20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9b30: 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  C] opcode is gen
9b40: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9b50: 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a  y by SQLite and.
9b60: 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  ** sent to the V
9b70: 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62  FS immediately b
9b80: 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20  efore the xSync 
9b90: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
9ba0: 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61  d on a.** databa
9bb0: 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  se file descript
9bc0: 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78  or. Or, if the x
9bd0: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e  Sync method is n
9be0: 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62  ot invoked .** b
9bf0: 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20  ecause the user 
9c00: 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53  has configured S
9c10: 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b  QLite with .** [
9c20: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9c30: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
9c40: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20  hronous=OFF] it 
9c50: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c  is invoked in pl
9c60: 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78  ace .** of the x
9c70: 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20  Sync method. In 
9c80: 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20  most cases, the 
9c90: 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
9ca0: 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20   passed with.** 
9cb0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
9cc0: 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76  l is NULL. Howev
9cd0: 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62  er, if the datab
9ce0: 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e  ase file is bein
9cf0: 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70  g synced.** as p
9d00: 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64  art of a multi-d
9d10: 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20  atabase commit, 
9d20: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  the argument poi
9d30: 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72  nts to a nul-ter
9d40: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
9d50: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
9d60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61   transactions ma
9d70: 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c  ster-journal fil
9d80: 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68  e name. VFSes th
9d90: 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65  at .** do not ne
9da0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73  ed this signal s
9db0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
9dc0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
9dd0: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
9de0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  .** should not c
9df0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
9e00: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9e10: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9e20: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a   doing so may .*
9e30: 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70  * disrupt the op
9e40: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9e50: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9e60: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9e70: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9e80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9e90: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
9ea0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9eb0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9ec0: 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69  ASETWO] opcode i
9ed0: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9ee0: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9ef0: 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  .** and sent to 
9f00: 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20  the VFS after a 
9f10: 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20  transaction has 
9f20: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69  been committed i
9f30: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75  mmediately.** bu
9f40: 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74  t before the dat
9f50: 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65  abase is unlocke
9f60: 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  d. VFSes that do
9f70: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9f80: 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20  ignal.** should 
9f90: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9fa0: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9fb0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9fc0: 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71   not call.** [sq
9fd0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9fe0: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9ff0: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
a000: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
a010: 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  he .** operation
a020: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
a030: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
a040: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
a050: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a060: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
a070: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
a080: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a090: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
a0a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a0b0: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
a0c0: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
a0d0: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
a0e0: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
a0f0: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
a100: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
a110: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
a120: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
a130: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
a140: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
a150: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
a160: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
a170: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
a180: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
a190: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
a1a0: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
a1b0: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
a1c0: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
a1d0: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
a1e0: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
a1f0: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
a200: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
a210: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
a220: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
a230: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
a240: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
a250: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
a260: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
a270: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
a280: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
a290: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
a2a0: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
a2b0: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
a2c0: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
a2d0: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
a2e0: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
a2f0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a300: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
a310: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
a320: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
a330: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
a340: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
a350: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
a360: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
a370: 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72  ger is the new r
a380: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
a390: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
a3a0: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
a3b0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
a3c0: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
a3d0: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
a3e0: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
a3f0: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
a400: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
a410: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
a420: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
a430: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
a440: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
a450: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
a460: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
a470: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
a480: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
a490: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
a4a0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
a4b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
a4c0: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
a4d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a4e0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
a4f0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a500: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a510: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
a520: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
a530: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
a540: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
a550: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
a560: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 28 5b  ite ahead log ([
a570: 57 41 4c 20 66 69 6c 65 5d 29 20 61 6e 64 20 73  WAL file]) and s
a580: 68 61 72 65 64 20 6d 65 6d 6f 72 79 0a 2a 2a 20  hared memory.** 
a590: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
a5a0: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
a5b0: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
a5c0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
a5d0: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
a5e0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
a5f0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
a600: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
a610: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a620: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
a630: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
a640: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
a650: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
a660: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
a670: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
a680: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
a690: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
a6a0: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
a6b0: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
a6c0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
a6d0: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
a6e0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
a6f0: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
a700: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
a710: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
a720: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
a730: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
a740: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
a750: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
a760: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a770: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a780: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a790: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a7a0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a7b0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a7c0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a7d0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
a7e0: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a7f0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a800: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
a810: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a820: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a830: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a840: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a850: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a860: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a870: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a880: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a890: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a8a0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a8b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a8c0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a8d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a8e0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a8f0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a900: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a910: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a920: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a930: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a940: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a950: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a960: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a970: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a980: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a990: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a9a0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a9b0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a9c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a9d0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a9e0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a9f0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
aa00: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
aa10: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
aa20: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
aa30: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
aa40: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
aa50: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
aa60: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
aa70: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
aa80: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
aa90: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
aaa0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
aab0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
aac0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
aad0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
aae0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
aaf0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
ab00: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
ab10: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
ab20: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
ab30: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
ab40: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
ab50: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
ab60: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
ab70: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
ab80: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
ab90: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
aba0: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
abb0: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
abc0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
abd0: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
abe0: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
abf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ac00: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
ac10: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ac20: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
ac30: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
ac40: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
ac50: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
ac60: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
ac70: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
ac80: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
ac90: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
aca0: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
acb0: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
acc0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
acd0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
ace0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
acf0: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
ad00: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
ad10: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
ad20: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
ad30: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
ad40: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
ad50: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
ad60: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
ad70: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
ad80: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
ad90: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
ada0: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
adb0: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
adc0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
add0: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
ade0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
adf0: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
ae00: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
ae10: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
ae20: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
ae30: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
ae40: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
ae50: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
ae60: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
ae70: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
ae80: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
ae90: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
aea0: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
aeb0: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
aec0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
aed0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d  TL_VFS_POINTER]]
aee0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
aef0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
af00: 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  ER] opcode finds
af10: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
af20: 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b  e top-level.** [
af30: 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79  VFSes] currently
af40: 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20   in use.  ^(The 
af50: 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a  argument X in.**
af60: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
af70: 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f  ntrol(db,SQLITE_
af80: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
af90: 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20  R,X) must be.** 
afa0: 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65  of type "[sqlite
afb0: 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69  3_vfs] **".  Thi
afc0: 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73  s opcodes will s
afd0: 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f  et *X.** to a po
afe0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
aff0: 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a  -level VFS.)^.**
b000: 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65   ^When there are
b010: 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68   multiple VFS sh
b020: 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b  ims in the stack
b030: 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69  , this opcode fi
b040: 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72  nds the.** upper
b050: 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e  -most shim only.
b060: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b070: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b080: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
b090: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
b0a0: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
b0b0: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
b0c0: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
b0d0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
b0e0: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
b0f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
b100: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
b110: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
b120: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
b130: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
b140: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
b150: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
b160: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
b170: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b180: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
b190: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
b1a0: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
b1b0: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
b1c0: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
b1d0: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
b1e0: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
b1f0: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
b200: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
b210: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
b220: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
b230: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
b240: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
b250: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
b260: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
b270: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
b280: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b290: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
b2a0: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
b2b0: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
b2c0: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
b2d0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
b2e0: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
b2f0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
b300: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
b310: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
b320: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
b330: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
b340: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
b350: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
b360: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
b370: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
b380: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
b390: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b3a0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b3b0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
b3c0: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
b3d0: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
b3e0: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
b3f0: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
b400: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b410: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
b420: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b430: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
b440: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
b450: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
b460: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
b470: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
b480: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
b490: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
b4a0: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
b4b0: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20  ed statement if 
b4c0: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73  result string is
b4d0: 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72   NULL, or that r
b4e0: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a  eturns a copy.**
b4f0: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
b500: 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72  tring if the str
b510: 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e  ing is non-NULL.
b520: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
b530: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b540: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b550: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
b560: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
b570: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b580: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
b590: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
b5a0: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
b5b0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
b5c0: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
b5d0: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
b5e0: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
b5f0: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
b600: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
b610: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
b620: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b630: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b640: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
b650: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
b660: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
b670: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
b680: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
b690: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
b6a0: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
b6b0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
b6c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b6d0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b6e0: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b6f0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b700: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
b710: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
b720: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
b730: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
b740: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
b750: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
b760: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
b770: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
b780: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
b790: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
b7a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
b7b0: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
b7c0: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
b7d0: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
b7e0: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
b7f0: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
b800: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
b810: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
b820: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
b830: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
b840: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
b850: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
b860: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
b870: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
b880: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
b890: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
b8a0: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
b8b0: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
b8c0: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
b8d0: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
b8e0: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
b8f0: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
b900: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
b910: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
b920: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
b930: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
b940: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
b950: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
b960: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
b970: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
b980: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b990: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b9a0: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
b9b0: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
b9c0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b9d0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
b9e0: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
b9f0: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
ba00: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
ba10: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
ba20: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
ba30: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
ba40: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
ba50: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
ba60: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
ba70: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
ba80: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
ba90: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
baa0: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
bab0: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
bac0: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
bad0: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
bae0: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
baf0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
bb00: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
bb10: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
bb20: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
bb30: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
bb40: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
bb50: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
bb60: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
bb70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bb80: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
bb90: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bba0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
bbb0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
bbc0: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
bbd0: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
bbe0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
bbf0: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
bc00: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
bc10: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
bc20: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
bc30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
bc40: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
bc50: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
bc60: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
bc70: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
bc80: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
bc90: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
bca0: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
bcb0: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
bcc0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
bcd0: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
bce0: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
bcf0: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
bd00: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
bd10: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
bd20: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
bd30: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
bd40: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
bd50: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
bd60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
bd70: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
bd80: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
bd90: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
bda0: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
bdb0: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
bdc0: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
bdd0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bde0: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
bdf0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
be00: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
be10: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
be20: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
be30: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
be40: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
be50: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
be60: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
be70: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
be80: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
be90: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
bea0: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
beb0: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
bec0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
bed0: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
bee0: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
bef0: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
bf00: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
bf10: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
bf20: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
bf30: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
bf40: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
bf50: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
bf60: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
bf70: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
bf80: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bf90: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bfa0: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
bfb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
bfc0: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
bfd0: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bfe0: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
bff0: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
c000: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
c010: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
c020: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
c030: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
c040: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
c050: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
c060: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
c070: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
c080: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
c090: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
c0a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c0b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
c0c0: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
c0d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
c0e0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_GET_HANDLE] 
c0f0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
c100: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
c110: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e  .** underlying n
c120: 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c  ative file handl
c130: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
c140: 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e  h a file handle.
c150: 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63    This file.** c
c160: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
c170: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
c180: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c190: 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e   native file han
c1a0: 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65  dle and.** write
c1b0: 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  s the resulting 
c1c0: 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a  value there..**.
c1d0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c1e0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
c1f0: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
c200: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
c210: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
c220: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
c230: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
c240: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
c250: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
c260: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
c270: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
c280: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
c290: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
c2a0: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
c2b0: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
c2c0: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
c2d0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
c2e0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
c2f0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
c300: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
c310: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
c320: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c330: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
c340: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c350: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
c360: 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  ] is a signal to
c370: 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74   the VFS layer t
c380: 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20  hat it might.** 
c390: 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20  be advantageous 
c3a0: 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  to block on the 
c3b0: 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66  next WAL lock if
c3c0: 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74   the lock is not
c3d0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
c3e0: 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20  available.  The 
c3f0: 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73  WAL subsystem is
c400: 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c  sues this signal
c410: 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20   during rare.** 
c420: 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e  circumstances in
c430: 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20   order to fix a 
c440: 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69  problem with pri
c450: 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e  ority inversion.
c460: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
c470: 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c   should <em>not<
c480: 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69  /em> use this fi
c490: 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a  le-control..**.*
c4a0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c4b0: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
c4c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c4d0: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
c4e0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
c4f0: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
c500: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
c510: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c520: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c530: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
c540: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c550: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a  ITE_FCNTL_RBU]].
c560: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c570: 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65  CNTL_RBU] opcode
c580: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c590: 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  by the special V
c5a0: 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68  FS used by.** th
c5b0: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
c5c0: 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72  only.  All other
c5d0: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
c5e0: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c5f0: 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f  ND for.** this o
c600: 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  pcode.  .**.** <
c610: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c620: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
c630: 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65  RITE]].** If the
c640: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
c650: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c660: 45 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 6e  E] opcode return
c670: 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65  s SQLITE_OK, the
c680: 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65  n.** the file de
c690: 73 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 63  scriptor is plac
c6a0: 65 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 69  ed in "batch wri
c6b0: 74 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a  te mode", which.
c6c0: 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62  ** means all sub
c6d0: 73 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70  sequent write op
c6e0: 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  erations will be
c6f0: 20 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 6f   deferred and do
c700: 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79  ne.** atomically
c710: 20 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 51   at the next [SQ
c720: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c730: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  T_ATOMIC_WRITE].
c740: 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61    Systems.** tha
c750: 74 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74  t do not support
c760: 20 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 72   batch atomic wr
c770: 69 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 6e  ites will return
c780: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
c790: 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20  ..** ^Following 
c7a0: 61 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 4c  a successful SQL
c7b0: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c7c0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e 64  ATOMIC_WRITE and
c7d0: 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65   prior to.** the
c7e0: 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45   closing [SQLITE
c7f0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
c800: 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a  OMIC_WRITE] or.*
c810: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
c820: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
c830: 57 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 77  WRITE], SQLite w
c840: 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56  ill make.** no V
c850: 46 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  FS interface cal
c860: 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ls on the same [
c870: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 69  sqlite3_file] fi
c880: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a  le descriptor.**
c890: 20 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c 6c   except for call
c8a0: 73 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 20  s to the xWrite 
c8b0: 6d 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 78  method and the x
c8c0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
c8d0: 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49  od.** with [SQLI
c8e0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
c8f0: 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  NT]..**.** <li>[
c900: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c910: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c920: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c930: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c940: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
c950: 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20  code causes all 
c960: 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69  write.** operati
c970: 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72  ons since the pr
c980: 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75  evious successfu
c990: 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53  l call to .** [S
c9a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c9b0: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
c9c0: 74 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  to be performed 
c9d0: 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54  atomically..** T
c9e0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c9f0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
ca00: 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  _OK] if and only
ca10: 20 69 66 20 74 68 65 20 77 72 69 74 65 73 20 77   if the writes w
ca20: 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f  ere.** all perfo
ca30: 72 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  rmed successfull
ca40: 79 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e 20  y and have been 
ca50: 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 72  committed to per
ca60: 73 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 2e  sistent storage.
ca70: 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
ca80: 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
ca90: 74 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66  t it is successf
caa0: 75 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 6f  ul, this file co
cab0: 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74  ntrol takes.** t
cac0: 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  he file descript
cad0: 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20  or out of batch 
cae0: 77 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 68  write mode so th
caf0: 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  at all subsequen
cb00: 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 61  t.** write opera
cb10: 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65  tions are indepe
cb20: 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ndent..** ^SQLit
cb30: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
cb40: 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  oke SQLITE_FCNTL
cb50: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
cb60: 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20  RITE without.** 
cb70: 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
cb80: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49  ul call to [SQLI
cb90: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
cba0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a  TOMIC_WRITE]..**
cbb0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
cbc0: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
cbd0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a  ATOMIC_WRITE]].*
cbe0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
cbf0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
cc00: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64  MIC_WRITE] opcod
cc10: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69  e causes all wri
cc20: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73  te.** operations
cc30: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69   since the previ
cc40: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63  ous successful c
cc50: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49  all to .** [SQLI
cc60: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
cc70: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20  TOMIC_WRITE] to 
cc80: 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  be rolled back..
cc90: 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 6f  ** ^This file co
cca0: 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 20  ntrol takes the 
ccb0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
ccc0: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69  out of batch wri
ccd0: 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68  te mode.** so th
cce0: 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  at all subsequen
ccf0: 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  t write operatio
cd00: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65  ns are independe
cd10: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  nt..** ^SQLite w
cd20: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
cd30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f   SQLITE_FCNTL_RO
cd40: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
cd50: 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  ITE without.** a
cd60: 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
cd70: 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54  l call to [SQLIT
cd80: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
cd90: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a  OMIC_WRITE]..**.
cda0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cdb0: 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f  FCNTL_LOCK_TIMEO
cdc0: 55 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  UT]].** The [SQL
cdd0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54  ITE_FCNTL_LOCK_T
cde0: 49 4d 45 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63  IMEOUT] opcode c
cdf0: 61 75 73 65 73 20 61 74 74 65 6d 70 74 73 20 74  auses attempts t
ce00: 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69  o obtain.** a fi
ce10: 6c 65 20 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68  le lock using th
ce20: 65 20 78 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c  e xLock or xShmL
ce30: 6f 63 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20 74  ock methods of t
ce40: 68 65 20 56 46 53 20 74 6f 20 77 61 69 74 0a 2a  he VFS to wait.*
ce50: 2a 20 66 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69  * for up to M mi
ce60: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
ce70: 65 20 66 61 69 6c 69 6e 67 2c 20 77 68 65 72 65  e failing, where
ce80: 20 4d 20 69 73 20 74 68 65 20 73 69 6e 67 6c 65   M is the single
ce90: 20 0a 2a 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e   .** unsigned in
cea0: 74 65 67 65 72 20 70 61 72 61 6d 65 74 65 72 2e  teger parameter.
ceb0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
cec0: 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56  ITE_FCNTL_DATA_V
ced0: 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20 54 68 65 20  ERSION]].** The 
cee0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41  [SQLITE_FCNTL_DA
cef0: 54 41 5f 56 45 52 53 49 4f 4e 5d 20 6f 70 63 6f  TA_VERSION] opco
cf00: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 64 65  de is used to de
cf10: 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  tect changes to.
cf20: 2a 2a 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ** a database fi
cf30: 6c 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  le.  The argumen
cf40: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
cf50: 6f 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67  o a 32-bit unsig
cf60: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20  ned integer..** 
cf70: 54 68 65 20 22 64 61 74 61 20 76 65 72 73 69 6f  The "data versio
cf80: 6e 22 20 66 6f 72 20 74 68 65 20 70 61 67 65 72  n" for the pager
cf90: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
cfa0: 20 74 68 65 20 70 6f 69 6e 74 65 72 2e 20 20 54   the pointer.  T
cfb0: 68 65 0a 2a 2a 20 22 64 61 74 61 20 76 65 72 73  he.** "data vers
cfc0: 69 6f 6e 22 20 63 68 61 6e 67 65 73 20 77 68 65  ion" changes whe
cfd0: 6e 65 76 65 72 20 61 6e 79 20 63 68 61 6e 67 65  never any change
cfe0: 20 6f 63 63 75 72 73 20 74 6f 20 74 68 65 20 63   occurs to the c
cff0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
d000: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 65  database file, e
d010: 69 74 68 65 72 20 74 68 72 6f 75 67 68 20 53 51  ither through SQ
d020: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
d030: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
d040: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  e.** connection,
d050: 20 6f 72 20 74 68 72 6f 75 67 68 20 74 72 61 6e   or through tran
d060: 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d 69 74 74  sactions committ
d070: 65 64 20 62 79 20 73 65 70 61 72 61 74 65 20 64  ed by separate d
d080: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
d090: 63 74 69 6f 6e 73 20 70 6f 73 73 69 62 6c 79 20  ctions possibly 
d0a0: 69 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  in other process
d0b0: 65 73 2e 20 54 68 65 20 5b 73 71 6c 69 74 65 33  es. The [sqlite3
d0c0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
d0d0: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 63  ].** interface c
d0e0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
d0f0: 6e 64 20 69 66 20 61 6e 79 20 64 61 74 61 62 61  nd if any databa
d100: 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63  se on the connec
d110: 74 69 6f 6e 20 68 61 73 20 63 68 61 6e 67 65 64  tion has changed
d120: 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74 20 69 6e  ,.** but that in
d130: 74 65 72 66 61 63 65 20 72 65 73 70 6f 6e 73 65  terface response
d140: 20 74 6f 20 63 68 61 6e 67 65 73 20 6f 6e 20 54   to changes on T
d150: 45 4d 50 20 61 73 20 77 65 6c 6c 20 61 73 20 4d  EMP as well as M
d160: 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a 2a 2a 20  AIN and does.** 
d170: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 6d 65  not provide a me
d180: 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 74 65 63  chanism to detec
d190: 74 20 63 68 61 6e 67 65 73 20 74 6f 20 4d 41 49  t changes to MAI
d1a0: 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f 2c 20 74  N only.  Also, t
d1b0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
d1c0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
d1d0: 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f 6e  interface respon
d1e0: 73 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 63  se to internal c
d1f0: 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61 6e 64 0a  hanges only and.
d200: 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e 67 65 73  ** omits changes
d210: 20 6d 61 64 65 20 62 79 20 6f 74 68 65 72 20 64   made by other d
d220: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d230: 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 5b 50 52  ons.  The.** [PR
d240: 41 47 4d 41 20 64 61 74 61 5f 76 65 72 73 69 6f  AGMA data_versio
d250: 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72 6f 76 69  n] command provi
d260: 64 65 20 61 20 6d 65 63 68 61 6e 69 73 6d 20 74  de a mechanism t
d270: 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73  o detect changes
d280: 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20   to.** a single 
d290: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
d2a0: 65 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 65  e that occur due
d2b0: 20 74 6f 20 6f 74 68 65 72 20 64 61 74 61 62 61   to other databa
d2c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 0a  se connections,.
d2d0: 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20 63 68 61  ** but omits cha
d2e0: 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  nges implemented
d2f0: 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
d300: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 66 6f 72 20   connection for 
d310: 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a 20 63  which it is.** c
d320: 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66 69 6c  alled.  This fil
d330: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74 68 65  e control is the
d340: 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73 6d 20   only mechanism 
d350: 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65  to detect change
d360: 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70 65 6e  s that.** happen
d370: 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c   either internal
d380: 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c 6c 79  ly or externally
d390: 20 6f 6e 20 61 20 73 69 6e 67 6c 65 20 64 61 74   on a single dat
d3a0: 61 62 61 73 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  abase..** </ul>.
d3b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d3c0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
d3d0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
d3e0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
d3f0: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
d400: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32  ROXYFILE       2
d410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d420: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
d430: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a  OXYFILE       3.
d440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d450: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  CNTL_LAST_ERRNO 
d460: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
d470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d480: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
d490: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
d4a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d4b0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
d4c0: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
d4d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d4e0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
d4f0: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
d500: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d510: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
d520: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
d530: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d540: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
d550: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
d560: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
d570: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
d580: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
d590: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
d5a0: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
d5b0: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
d5c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
d5d0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
d5e0: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
d5f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
d600: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
d610: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
d620: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
d630: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
d640: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
d650: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
d660: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
d670: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
d680: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
d690: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
d6a0: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
d6b0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
d6c0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
d6d0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
d6e0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
d6f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
d700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d710: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20  FCNTL_HAS_MOVED 
d720: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a               20.
d730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d740: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20  CNTL_SYNC       
d750: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23              21.#
d760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d770: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
d780: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64  TWO        22.#d
d790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d7a0: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
d7b0: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65  DLE       23.#de
d7c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d7d0: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20  L_WAL_BLOCK     
d7e0: 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66           24.#def
d7f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d800: 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20  _ZIPVFS         
d810: 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69          25.#defi
d820: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d830: 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20  RBU             
d840: 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e         26.#defin
d850: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
d860: 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  FS_POINTER      
d870: 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65        27.#define
d880: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f   SQLITE_FCNTL_JO
d890: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20  URNAL_POINTER   
d8a0: 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20       28.#define 
d8b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
d8c0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_GET_HANDLE   
d8d0: 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53      29.#define S
d8e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20  QLITE_FCNTL_PDB 
d8f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d900: 20 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53 51     30.#define SQ
d910: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
d920: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20  _ATOMIC_WRITE   
d930: 20 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    31.#define SQL
d940: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
d950: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20  _ATOMIC_WRITE   
d960: 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   32.#define SQLI
d970: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
d980: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20  K_ATOMIC_WRITE  
d990: 33 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  33.#define SQLIT
d9a0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d  E_FCNTL_LOCK_TIM
d9b0: 45 4f 55 54 20 20 20 20 20 20 20 20 20 20 20 33  EOUT           3
d9c0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
d9d0: 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53  _FCNTL_DATA_VERS
d9e0: 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 33 35  ION           35
d9f0: 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20  ../* deprecated 
da00: 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  names */.#define
da10: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
da20: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
da30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
da40: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
da50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
da60: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
da70: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
da80: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
da90: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
daa0: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
dab0: 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f           SQLITE_
dac0: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
dad0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
dae0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
daf0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
db00: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
db10: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
db20: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
db30: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
db40: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
db50: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
db60: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
db70: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
db80: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
db90: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
dba0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
dbb0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
dbc0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
dbd0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
dbe0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
dbf0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
dc00: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
dc10: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
dc20: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
dc30: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
dc40: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
dc50: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
dc60: 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c  API3REF: Loadabl
dc70: 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e  e Extension Thun
dc80: 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  k.**.** A pointe
dc90: 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20  r to the opaque 
dca0: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
dcb0: 69 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69  ines structure i
dcc0: 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  s passed as.** t
dcd0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
dce0: 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e  er to entry poin
dcf0: 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20  ts of [loadable 
dd00: 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68  extensions].  Th
dd10: 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  is.** structure 
dd20: 6d 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65  must be typedefe
dd30: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f  d in order to wo
dd40: 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c  rk around compil
dd50: 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f  er warnings.** o
dd60: 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73  n some platforms
dd70: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
dd80: 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
dd90: 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33  routines sqlite3
dda0: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a  _api_routines;..
ddb0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ddc0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
ddd0: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
dde0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
ddf0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
de00: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
de10: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
de20: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
de30: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
de40: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
de50: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
de60: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
de70: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
de80: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
de90: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
dea0: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
deb0: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
dec0: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
ded0: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
dee0: 2a 0a 2a 2a 20 54 68 65 20 56 46 53 20 69 6e 74  *.** The VFS int
def0: 65 72 66 61 63 65 20 69 73 20 73 6f 6d 65 74 69  erface is someti
df00: 6d 65 73 20 65 78 74 65 6e 64 65 64 20 62 79 20  mes extended by 
df10: 61 64 64 69 6e 67 20 6e 65 77 20 6d 65 74 68 6f  adding new metho
df20: 64 73 20 6f 6e 74 6f 0a 2a 2a 20 74 68 65 20 65  ds onto.** the e
df30: 6e 64 2e 20 20 45 61 63 68 20 74 69 6d 65 20 73  nd.  Each time s
df40: 75 63 68 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e  uch an extension
df50: 20 6f 63 63 75 72 73 2c 20 74 68 65 20 69 56 65   occurs, the iVe
df60: 72 73 69 6f 6e 20 66 69 65 6c 64 0a 2a 2a 20 69  rsion field.** i
df70: 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 20 20  s incremented.  
df80: 54 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  The iVersion val
df90: 75 65 20 73 74 61 72 74 65 64 20 6f 75 74 20 61  ue started out a
dfa0: 73 20 31 20 69 6e 0a 2a 2a 20 53 51 4c 69 74 65  s 1 in.** SQLite
dfb0: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 5d   [version 3.5.0]
dfc0: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 35 2e   on [dateof:3.5.
dfd0: 30 5d 2c 20 74 68 65 6e 20 69 6e 63 72 65 61 73  0], then increas
dfe0: 65 64 20 74 6f 20 32 0a 2a 2a 20 77 69 74 68 20  ed to 2.** with 
dff0: 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20  SQLite [version 
e000: 33 2e 37 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f  3.7.0] on [dateo
e010: 66 3a 33 2e 37 2e 30 5d 2c 20 61 6e 64 20 74 68  f:3.7.0], and th
e020: 65 6e 20 69 6e 63 72 65 61 73 65 64 0a 2a 2a 20  en increased.** 
e030: 74 6f 20 33 20 77 69 74 68 20 53 51 4c 69 74 65  to 3 with SQLite
e040: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 36 5d   [version 3.7.6]
e050: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e   on [dateof:3.7.
e060: 36 5d 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  6].  Additional 
e070: 66 69 65 6c 64 73 0a 2a 2a 20 6d 61 79 20 62 65  fields.** may be
e080: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65   appended to the
e090: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
e0a0: 65 63 74 20 61 6e 64 20 74 68 65 20 69 56 65 72  ect and the iVer
e0b0: 73 69 6f 6e 20 76 61 6c 75 65 0a 2a 2a 20 6d 61  sion value.** ma
e0c0: 79 20 69 6e 63 72 65 61 73 65 20 61 67 61 69 6e  y increase again
e0d0: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
e0e0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
e0f0: 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
e100: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
e110: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
e120: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
e130: 6e 20 74 68 65 20 74 72 61 6e 73 69 74 69 6f 6e  n the transition
e140: 20 66 72 6f 6d 0a 2a 2a 20 53 51 4c 69 74 65 20   from.** SQLite 
e150: 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 5d 20  [version 3.5.9] 
e160: 74 6f 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e  to [version 3.6.
e170: 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e  0] on [dateof:3.
e180: 36 2e 30 5d 0a 2a 2a 20 61 6e 64 20 79 65 74 20  6.0].** and yet 
e190: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
e1a0: 6c 64 20 77 61 73 20 6e 6f 74 20 6d 6f 64 69 66  ld was not modif
e1b0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
e1c0: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
e1d0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
e1e0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
e1f0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
e200: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
e210: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
e220: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
e230: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
e240: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
e250: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
e260: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
e270: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
e280: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
e290: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
e2a0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
e2b0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
e2c0: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
e2d0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
e2e0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
e2f0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
e300: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
e310: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
e320: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
e330: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
e340: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
e350: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
e360: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
e370: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
e380: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
e390: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
e3a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
e3b0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
e3c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
e3d0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
e3e0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
e3f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
e400: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
e410: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
e420: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
e430: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
e440: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
e450: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
e460: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
e470: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
e480: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
e490: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
e4a0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
e4b0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
e4c0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
e4d0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
e4e0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
e4f0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
e500: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
e510: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
e520: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
e530: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
e540: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
e550: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
e560: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
e570: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
e580: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
e590: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
e5a0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e5b0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
e5c0: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
e5d0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
e5e0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
e5f0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
e600: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
e610: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
e620: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
e630: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
e640: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
e650: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
e660: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
e670: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
e680: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
e690: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
e6a0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
e6b0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
e6c0: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
e6d0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
e6e0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
e6f0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
e700: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
e710: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
e720: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
e730: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
e740: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
e750: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
e760: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
e770: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
e780: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
e790: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
e7a0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
e7b0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
e7c0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
e7d0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
e7e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
e7f0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
e800: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
e810: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
e820: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
e830: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
e840: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
e850: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
e860: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
e870: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
e880: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
e890: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
e8a0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
e8b0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
e8c0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e8d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
e8e0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
e8f0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
e900: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
e910: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
e920: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
e930: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
e940: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
e950: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
e960: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
e970: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
e980: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
e990: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
e9a0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
e9b0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
e9c0: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
e9d0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
e9e0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
e9f0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
ea00: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
ea10: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
ea20: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
ea30: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
ea40: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
ea50: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
ea60: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
ea70: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
ea80: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
ea90: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
eaa0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
eab0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
eac0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
ead0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
eae0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
eaf0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
eb00: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
eb10: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
eb20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
eb30: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
eb40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
eb50: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
eb60: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
eb70: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
eb80: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
eb90: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
eba0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ebb0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
ebc0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ebd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
ebe0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
ebf0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
ec00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
ec10: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
ec20: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
ec30: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
ec40: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
ec50: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
ec60: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
ec70: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
ec80: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
ec90: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
eca0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
ecb0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
ecc0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
ecd0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
ece0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
ecf0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
ed00: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
ed10: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
ed20: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
ed30: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
ed40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
ed50: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
ed60: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
ed70: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
ed80: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
ed90: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
eda0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
edb0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
edc0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
edd0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
ede0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
edf0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
ee00: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
ee10: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
ee20: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
ee30: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
ee40: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
ee50: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
ee60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
ee70: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
ee80: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
ee90: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
eea0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
eeb0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
eec0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
eed0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
eee0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
eef0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
ef00: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
ef10: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
ef20: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
ef30: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
ef40: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
ef50: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
ef60: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
ef70: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
ef80: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
ef90: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
efa0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
efb0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
efc0: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
efd0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
efe0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
eff0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
f000: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
f010: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
f020: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
f030: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
f040: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
f050: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
f060: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
f070: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
f080: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
f090: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
f0a0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
f0b0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
f0c0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
f0d0: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
f0e0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
f0f0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
f100: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
f110: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
f120: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
f130: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
f140: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
f150: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
f160: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
f170: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
f180: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
f190: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
f1a0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
f1b0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
f1c0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
f1d0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
f1e0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
f1f0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
f200: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
f210: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
f220: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
f230: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
f240: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
f250: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
f260: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
f270: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
f280: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
f290: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
f2a0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
f2b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
f2c0: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
f2d0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
f2e0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
f2f0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
f300: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
f310: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
f320: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
f330: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
f340: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
f350: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
f360: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
f370: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
f380: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
f390: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
f3a0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
f3b0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
f3c0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
f3d0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
f3e0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
f3f0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
f400: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
f410: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
f420: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
f430: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
f440: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
f450: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
f460: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
f470: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
f480: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
f490: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
f4a0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
f4b0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
f4c0: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
f4d0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
f4e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
f4f0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
f500: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
f510: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
f520: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
f530: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
f540: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
f550: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
f560: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
f570: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
f580: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
f590: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
f5a0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
f5b0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
f5c0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
f5d0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
f5e0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
f5f0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
f600: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
f610: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
f620: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
f630: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
f640: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
f650: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
f660: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
f670: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
f680: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
f690: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
f6a0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
f6b0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
f6c0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
f6d0: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
f6e0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
f6f0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
f700: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
f710: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
f720: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
f730: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
f740: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
f750: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
f760: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
f770: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
f780: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
f790: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
f7a0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
f7b0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
f7c0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
f7d0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
f7e0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
f7f0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
f800: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
f810: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
f820: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
f830: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
f840: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
f850: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
f860: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
f870: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
f880: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
f890: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
f8a0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
f8b0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
f8c0: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
f8d0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
f8e0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
f8f0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f900: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
f910: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
f920: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
f930: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
f940: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
f950: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
f960: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
f970: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
f980: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
f990: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
f9a0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f9b0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
f9c0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
f9d0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
f9e0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
f9f0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
fa00: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
fa10: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
fa20: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
fa30: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
fa40: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
fa50: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
fa60: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
fa70: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
fa80: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
fa90: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
faa0: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
fab0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
fac0: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
fad0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
fae0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
faf0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
fb00: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
fb10: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
fb20: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
fb30: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
fb40: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
fb50: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
fb60: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
fb70: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
fb80: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
fb90: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
fba0: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
fbb0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
fbc0: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
fbd0: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
fbe0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
fbf0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
fc00: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
fc10: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
fc20: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
fc30: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
fc40: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
fc50: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
fc60: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
fc70: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
fc80: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
fc90: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
fca0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
fcb0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
fcc0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
fcd0: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
fce0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
fcf0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
fd00: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
fd10: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
fd20: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
fd30: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
fd40: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
fd50: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
fd60: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
fd70: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
fd80: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
fd90: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
fda0: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
fdb0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
fdc0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
fdd0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
fde0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
fdf0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
fe00: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
fe10: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
fe20: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
fe30: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
fe40: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
fe50: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
fe60: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
fe70: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
fe80: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
fe90: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
fea0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
feb0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
fec0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
fed0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
fee0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
fef0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
ff00: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
ff10: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
ff20: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
ff30: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
ff40: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
ff50: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
ff60: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
ff70: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
ff80: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
ff90: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
ffa0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
ffb0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
ffc0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ffd0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
ffe0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
fff0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
10000 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
10010 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
10020 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
10030 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
10040 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
10050 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
10060 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
10070 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
10080 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
10090 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
100a0 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
100b0 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
100c0 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
100d0 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
100e0 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
100f0 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
10100 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10110 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
10120 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
10130 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
10140 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
10150 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
10160 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
10170 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
10180 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
10190 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
101a0 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
101b0 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
101c0 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
101d0 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
101e0 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
101f0 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
10200 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
10210 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
10220 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
10230 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
10240 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
10250 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
10260 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
10270 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
10280 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10290 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
102a0 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
102b0 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
102c0 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
102d0 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
102e0 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
102f0 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
10300 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
10310 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
10320 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
10330 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
10340 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
10350 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
10360 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
10370 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
10380 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
10390 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
103a0 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
103b0 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
103c0 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
103d0 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
103e0 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
103f0 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
10400 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10410 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
10420 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
10430 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
10440 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
10450 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
10460 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10470 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10480 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
10490 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
104a0 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
104b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
104c0 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
104d0 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
104e0 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
104f0 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
10500 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
10510 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
10520 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
10530 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72  ppended in futur
10540 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
10550 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
10560 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
10570 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
10580 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
10590 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
105a0 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
105b0 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
105c0 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
105d0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
105e0 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
105f0 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
10600 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
10610 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
10620 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
10630 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
10640 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
10650 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
10660 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
10670 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
10680 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
10690 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
106a0 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
106b0 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
106c0 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
106d0 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
106e0 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
106f0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10700 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
10710 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
10720 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
10730 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
10740 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
10750 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
10760 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
10770 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
10780 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
10790 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
107a0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
107b0 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
107c0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
107d0 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
107e0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
107f0 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
10800 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
10810 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
10820 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
10830 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
10840 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
10850 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
10860 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
10870 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
10880 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
10890 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
108a0 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
108b0 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
108c0 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
108d0 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
108e0 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
108f0 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
10900 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
10910 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
10920 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
10930 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
10940 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
10950 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10960 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
10970 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
10980 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
10990 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
109a0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
109b0 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
109c0 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
109d0 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
109e0 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
109f0 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
10a00 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
10a10 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
10a20 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
10a30 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
10a40 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
10a50 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
10a60 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
10a70 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
10a80 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
10a90 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
10aa0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
10ab0 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
10ac0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
10ad0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
10ae0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
10af0 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
10b00 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
10b10 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
10b20 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
10b30 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
10b40 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
10b50 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
10b60 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
10b70 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10b80 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
10b90 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
10ba0 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
10bb0 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
10bc0 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
10bd0 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
10be0 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
10bf0 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
10c00 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
10c10 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
10c20 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
10c30 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
10c40 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
10c50 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
10c60 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
10c70 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
10c80 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
10c90 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
10ca0 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
10cb0 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
10cc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
10cd0 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
10ce0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
10cf0 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
10d00 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
10d10 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
10d20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
10d30 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10d40 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
10d50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
10d60 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
10d70 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
10d80 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
10d90 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
10da0 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
10db0 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
10dc0 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
10dd0 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
10de0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
10df0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
10e00 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
10e10 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
10e20 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
10e30 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
10e40 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
10e50 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
10e60 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
10e70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
10e80 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
10e90 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
10ea0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
10eb0 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
10ec0 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
10ed0 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
10ee0 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
10ef0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
10f00 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
10f10 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
10f20 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
10f30 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
10f40 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10f50 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
10f60 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
10f70 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
10f80 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
10f90 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
10fa0 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
10fb0 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
10fc0 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
10fd0 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
10fe0 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
10ff0 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
11000 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
11010 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
11020 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
11030 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
11040 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
11050 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
11060 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
11070 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11080 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
11090 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
110a0 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
110b0 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
110c0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
110d0 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
110e0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
110f0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
11100 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
11110 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
11120 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
11130 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
11140 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11150 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
11160 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
11170 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
11180 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
11190 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
111a0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
111b0 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
111c0 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
111d0 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
111e0 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
111f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11200 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
11210 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11220 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
11230 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
11240 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
11250 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
11260 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
11270 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
11280 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
11290 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
112a0 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
112b0 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
112c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
112d0 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
112e0 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
112f0 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
11300 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
11310 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
11320 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
11330 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
11340 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
11350 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
11360 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
11370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11380 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
11390 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
113a0 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
113b0 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
113c0 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
113d0 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
113e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
113f0 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
11400 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
11410 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11420 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
11430 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
11440 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
11450 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
11460 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
11470 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
11480 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
11490 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
114a0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
114b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
114c0 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
114d0 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
114e0 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
114f0 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
11500 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
11510 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
11520 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
11530 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
11540 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
11550 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
11560 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
11570 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
11580 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
11590 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
115a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
115b0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
115c0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
115d0 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
115e0 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
115f0 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
11600 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
11610 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
11620 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
11630 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
11640 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
11650 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
11660 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
11670 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
11680 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11690 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
116a0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
116b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
116c0 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
116d0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
116e0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
116f0 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
11700 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
11710 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
11720 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
11730 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
11740 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
11750 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
11760 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
11770 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
11780 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
11790 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
117a0 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
117b0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
117c0 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
117d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
117e0 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
117f0 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
11800 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
11810 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
11820 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
11830 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
11840 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
11850 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
11860 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
11870 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
11880 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
11890 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
118a0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
118b0 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
118c0 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
118d0 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
118e0 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
118f0 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
11900 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
11910 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
11920 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
11930 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
11940 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
11950 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
11960 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
11970 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
11980 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
11990 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
119a0 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
119b0 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
119c0 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
119d0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
119e0 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
119f0 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
11a00 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
11a10 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
11a20 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
11a30 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
11a40 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
11a50 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
11a60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
11a70 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
11a80 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
11a90 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
11aa0 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
11ab0 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
11ac0 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
11ad0 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
11ae0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
11af0 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
11b00 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
11b10 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
11b20 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
11b30 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
11b40 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
11b50 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
11b60 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
11b70 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11b80 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
11b90 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
11ba0 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
11bb0 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
11bc0 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
11bd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
11be0 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
11bf0 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
11c00 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
11c10 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
11c20 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
11c30 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
11c40 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
11c50 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11c60 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
11c70 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11c80 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
11c90 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
11ca0 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
11cb0 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
11cc0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
11cd0 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
11ce0 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
11cf0 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
11d00 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
11d10 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
11d20 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
11d30 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
11d40 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
11d50 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
11d60 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
11d70 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
11d80 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
11d90 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
11da0 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
11db0 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
11dc0 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
11dd0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
11de0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
11df0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
11e00 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
11e10 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
11e20 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
11e30 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
11e40 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
11e50 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
11e60 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
11e70 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
11e80 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
11e90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
11ea0 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
11eb0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
11ec0 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
11ed0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
11ee0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
11ef0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
11f00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11f10 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
11f20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
11f30 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
11f40 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
11f50 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
11f60 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
11f70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
11f80 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
11f90 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
11fa0 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
11fb0 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
11fc0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
11fd0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
11fe0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
11ff0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
12000 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
12010 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
12020 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
12030 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
12040 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
12050 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
12060 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
12070 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
12080 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
12090 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
120a0 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
120b0 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
120c0 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
120d0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
120e0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
120f0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
12100 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
12110 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
12120 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
12130 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
12140 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
12150 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
12160 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
12170 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
12180 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
12190 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
121a0 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
121b0 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
121c0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
121d0 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
121e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
121f0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
12200 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
12210 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
12220 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12230 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
12240 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
12250 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
12260 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
12270 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
12280 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
12290 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
122a0 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
122b0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
122c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
122d0 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
122e0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
122f0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
12300 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
12310 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
12320 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
12330 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
12340 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12350 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
12360 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
12370 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
12380 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
12390 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
123a0 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
123b0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
123c0 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
123d0 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
123e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
123f0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
12400 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
12410 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
12420 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12430 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
12440 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
12450 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
12460 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
12470 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
12480 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
12490 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
124a0 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
124b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
124c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
124d0 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
124e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
124f0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
12500 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
12510 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
12520 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
12530 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12540 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
12550 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
12560 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
12570 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
12580 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
12590 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
125a0 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
125b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
125c0 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
125d0 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
125e0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
125f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12600 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
12610 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12620 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
12630 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12640 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
12650 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
12660 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
12670 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12680 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
12690 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
126a0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
126b0 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
126c0 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
126d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
126e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
126f0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
12700 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
12710 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
12720 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
12730 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
12740 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
12750 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
12760 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
12770 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
12780 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
12790 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
127a0 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
127b0 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
127c0 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
127d0 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
127e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
127f0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
12800 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
12810 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12820 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
12830 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
12840 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
12850 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
12860 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12870 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
12880 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
12890 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
128a0 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
128b0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
128c0 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
128d0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
128e0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
128f0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
12900 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12910 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
12920 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12930 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
12940 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
12950 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
12960 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
12970 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
12980 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12990 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
129a0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
129b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
129c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
129d0 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
129e0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
129f0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
12a00 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
12a10 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
12a20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12a30 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
12a40 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
12a50 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
12a60 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
12a70 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
12a80 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
12a90 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
12aa0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
12ab0 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
12ac0 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
12ad0 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
12ae0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
12af0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
12b00 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
12b10 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
12b20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
12b30 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
12b40 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
12b50 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
12b60 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
12b70 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
12b80 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
12b90 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
12ba0 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
12bb0 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
12bc0 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
12bd0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
12be0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
12bf0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
12c00 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
12c10 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
12c20 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
12c30 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
12c40 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
12c50 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
12c60 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
12c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
12c80 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
12c90 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
12ca0 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
12cb0 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
12cc0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
12cd0 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
12ce0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
12cf0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
12d00 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
12d10 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
12d20 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
12d30 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
12d40 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
12d50 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
12d60 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
12d70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
12d80 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
12d90 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
12da0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
12db0 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
12dc0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
12dd0 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
12de0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
12df0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
12e00 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
12e10 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
12e20 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
12e30 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
12e40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
12e50 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
12e60 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
12e70 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
12e80 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
12e90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
12ea0 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
12eb0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
12ec0 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
12ed0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
12ee0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
12ef0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
12f00 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
12f10 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
12f20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
12f30 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
12f40 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
12f50 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
12f60 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
12f70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
12f80 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
12f90 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
12fa0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
12fb0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
12fc0 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
12fd0 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
12fe0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
12ff0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
13000 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
13010 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
13020 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
13030 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
13040 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
13050 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
13060 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
13070 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
13080 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
13090 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
130a0 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
130b0 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
130c0 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
130d0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
130e0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
130f0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
13100 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13110 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
13120 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
13130 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
13140 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
13150 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
13160 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
13170 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
13180 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
13190 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
131a0 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
131b0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
131c0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
131d0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
131e0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
131f0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
13200 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
13210 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
13220 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
13230 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
13240 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
13250 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
13260 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
13270 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
13280 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
13290 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
132a0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
132b0 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
132c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
132d0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
132e0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
132f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
13300 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
13310 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13320 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
13330 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
13340 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
13350 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
13360 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
13370 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
13380 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
13390 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
133a0 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
133b0 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
133c0 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
133d0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
133e0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
133f0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
13400 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
13410 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
13420 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
13430 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
13440 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
13450 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
13460 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
13470 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
13480 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
13490 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
134a0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
134b0 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
134c0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
134d0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
134e0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
134f0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
13500 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13510 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
13520 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
13530 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
13540 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
13550 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
13560 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
13570 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
13580 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
13590 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
135a0 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
135b0 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
135c0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
135d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
135e0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
135f0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
13600 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
13610 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
13620 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
13630 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
13640 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
13650 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
13660 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13670 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
13680 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
13690 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
136a0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
136b0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
136c0 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
136d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
136e0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
136f0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
13700 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
13710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
13720 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
13730 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
13740 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
13750 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
13760 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
13770 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
13780 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
13790 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
137a0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
137b0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
137c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
137d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
137e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
137f0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
13800 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
13810 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
13820 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
13830 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
13840 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
13850 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
13860 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
13870 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
13880 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
13890 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
138a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
138b0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
138c0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
138d0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
138e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
138f0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
13900 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
13910 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
13920 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
13930 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
13940 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
13950 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
13960 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
13970 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
13980 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
13990 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
139a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
139b0 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
139c0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
139d0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
139e0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
139f0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
13a00 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
13a10 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
13a20 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
13a30 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
13a40 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
13a50 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
13a60 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
13a70 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
13a80 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
13a90 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
13aa0 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
13ab0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13ac0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13ad0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13ae0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13af0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13b00 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
13b10 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
13b20 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
13b30 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13b40 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
13b50 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
13b60 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
13b70 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
13b80 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
13b90 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
13ba0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
13bb0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
13bc0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
13bd0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
13be0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
13bf0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13c00 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
13c10 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
13c20 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
13c30 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
13c40 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
13c50 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
13c60 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
13c70 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
13c80 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13c90 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
13ca0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
13cb0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
13cc0 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
13cd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13ce0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
13cf0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
13d00 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
13d10 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
13d20 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
13d30 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
13d40 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13d50 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
13d60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13d70 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
13d80 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
13d90 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
13da0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
13db0 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
13dc0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
13dd0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
13de0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
13df0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
13e00 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
13e10 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
13e20 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
13e30 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
13e40 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13e50 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13e60 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13e70 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13e80 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13e90 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13ea0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
13eb0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
13ec0 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
13ed0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13ee0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
13ef0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
13f00 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13f10 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
13f20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
13f30 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
13f40 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
13f50 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
13f60 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13f70 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
13f80 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
13f90 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
13fa0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
13fb0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
13fc0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
13fd0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
13fe0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
13ff0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
14000 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
14010 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
14020 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
14030 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
14040 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
14050 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
14060 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
14070 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
14080 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14090 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
140a0 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
140b0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
140c0 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
140d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
140e0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
140f0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
14100 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
14110 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
14120 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
14130 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
14140 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
14150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
14160 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
14170 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
14180 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
14190 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
141a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
141b0 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
141c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
141d0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
141e0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
141f0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
14200 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14210 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
14220 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
14230 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
14240 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
14250 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
14260 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
14270 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
14280 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
14290 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
142a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
142b0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
142c0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
142d0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
142e0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
142f0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
14300 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14310 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
14320 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14330 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
14340 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14350 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
14360 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14370 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
14380 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14390 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
143a0 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
143b0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
143c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
143d0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
143e0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
143f0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
14400 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
14410 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
14420 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
14430 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
14440 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
14450 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
14460 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
14470 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
14480 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
14490 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
144a0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
144b0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
144c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
144d0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
144e0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
144f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14500 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
14510 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14520 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
14530 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
14540 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
14550 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
14560 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14570 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
14580 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14590 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
145a0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
145b0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
145c0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
145d0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
145e0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
145f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
14600 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
14610 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
14620 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
14630 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
14640 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
14650 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
14660 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
14670 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
14680 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
14690 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
146a0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
146b0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
146c0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
146d0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
146e0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
146f0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
14700 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
14710 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14720 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c  ONFIG_SMALL_MALL
14730 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
14740 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c  CONFIG_SMALL_MAL
14750 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
14760 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14770 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43  FIG_SMALL_MALLOC
14780 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
14790 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
147a0 0a 2a 2a 20 74 79 70 65 20 69 6e 74 2c 20 69 6e  .** type int, in
147b0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
147c0 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 69 66  oolean, which if
147d0 20 74 72 75 65 20 70 72 6f 76 69 64 65 73 20 61   true provides a
147e0 20 68 69 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 69   hint to.** SQLi
147f0 74 65 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c  te that it shoul
14800 64 20 61 76 6f 69 64 20 6c 61 72 67 65 20 6d 65  d avoid large me
14810 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
14820 20 69 66 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a   if possible..**
14830 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 72 75 6e   SQLite will run
14840 20 66 61 73 74 65 72 20 69 66 20 69 74 20 69 73   faster if it is
14850 20 66 72 65 65 20 74 6f 20 6d 61 6b 65 20 6c 61   free to make la
14860 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  rge memory alloc
14870 61 74 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 73  ations,.** but s
14880 6f 6d 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ome application 
14890 6d 69 67 68 74 20 70 72 65 66 65 72 20 74 6f 20  might prefer to 
148a0 72 75 6e 20 73 6c 6f 77 65 72 20 69 6e 20 65 78  run slower in ex
148b0 63 68 61 6e 67 65 20 66 6f 72 0a 2a 2a 20 67 75  change for.** gu
148c0 61 72 61 6e 74 65 65 73 20 61 62 6f 75 74 20 6d  arantees about m
148d0 65 6d 6f 72 79 20 66 72 61 67 6d 65 6e 74 61 74  emory fragmentat
148e0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 70 6f 73  ion that are pos
148f0 73 69 62 6c 65 20 69 66 20 6c 61 72 67 65 0a 2a  sible if large.*
14900 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 72  * allocations ar
14910 65 20 61 76 6f 69 64 65 64 2e 20 20 54 68 69 73  e avoided.  This
14920 20 68 69 6e 74 20 69 73 20 6e 6f 72 6d 61 6c 6c   hint is normall
14930 79 20 6f 66 66 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  y off..** </dd>.
14940 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14950 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
14960 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14970 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
14980 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
149a0 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
149b0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
149c0 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
149d0 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
149e0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
149f0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
14a00 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
14a10 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
14a20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14a30 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
14a40 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
14a50 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
14a60 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
14a70 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
14a80 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
14a90 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
14aa0 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
14ab0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
14ac0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
14ad0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
14ae0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
14af0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
14b00 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
14b10 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
14b20 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14b30 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
14b40 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
14b50 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
14b60 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
14b70 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
14b80 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
14b90 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
14ba0 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
14bb0 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
14bc0 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
14bd0 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
14be0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14bf0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
14c00 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
14c10 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14c20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14c30 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
14c40 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14c50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68  </dt>.** <dd> Th
14c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14c70 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 69  SCRATCH option i
14c80 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  s no longer used
14c90 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14ca0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14cb0 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
14cc0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
14cd0 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
14ce0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14cf0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14d00 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  HE option specif
14d10 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f  ies a memory poo
14d20 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  l.** that SQLite
14d30 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
14d40 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
14d50 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
14d60 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
14d70 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14d80 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
14d90 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14da0 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66  on is a no-op if
14db0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
14dc0 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
14dd0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
14de0 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
14df0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
14e00 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e  CONFIG_PCACHE2].
14e10 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
14e20 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
14e30 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
14e40 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69  PAGECACHE: A poi
14e50 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74  nter to.** 8-byt
14e60 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  e aligned memory
14e70 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a   (pMem), the siz
14e80 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63  e of each page c
14e90 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a  ache line (sz),.
14ea0 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ** and the numbe
14eb0 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73  r of cache lines
14ec0 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
14ed0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
14ee0 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
14ef0 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
14f00 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
14f10 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
14f20 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33  een 512 and 6553
14f30 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  6) plus some ext
14f40 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
14f50 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
14f60 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
14f70 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
14f80 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
14f90 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
14fa0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
14fb0 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ng [SQLITE_CONFI
14fc0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e  G_PCACHE_HDRSZ].
14fd0 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  .** ^It is harml
14fe0 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
14ff0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
15000 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a  y,.** for the sz
15010 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
15020 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63   larger than nec
15030 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65  essary.  The pMe
15040 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  m.** argument mu
15050 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
15060 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  ULL pointer or a
15070 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
15080 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
15090 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
150a0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
150b0 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69  N bytes, otherwi
150c0 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  se.** subsequent
150d0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
150e0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e  efined..** ^When
150f0 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c   pMem is not NUL
15100 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73  L, SQLite will s
15110 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65  trive to use the
15120 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
15130 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70  .** to satisfy p
15140 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c  age cache needs,
15150 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f   falling back to
15160 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15170 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65  ()] if.** a page
15180 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c   cache line is l
15190 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79  arger than sz by
151a0 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66  tes or if all of
151b0 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72   the pMem buffer
151c0 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64  .** is exhausted
151d0 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73  ..** ^If pMem is
151e0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e   NULL and N is n
151f0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61  on-zero, then ea
15200 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
15210 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61  ection.** does a
15220 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61  n initial bulk a
15230 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61  llocation for pa
15240 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a  ge cache memory.
15250 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
15260 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69  _malloc()] suffi
15270 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68  cient for N cach
15280 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20  e lines if N is 
15290 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f  positive or.** o
152a0 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20  f -1024*N bytes 
152b0 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
152c0 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  , . ^If addition
152d0 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
152e0 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
152f0 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
15300 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
15310 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f   initial.** allo
15320 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c  cation, then SQL
15330 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
15340 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
15350 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61  eparately for ea
15360 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  ch.** additional
15370 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64   cache line. </d
15380 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15390 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
153a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
153b0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
153c0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
153d0 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
153e0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
153f0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
15400 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
15410 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
15420 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
15430 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
15440 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
15450 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
15460 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
15470 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15480 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53  ACHE]..** ^The S
15490 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
154a0 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  P option is only
154b0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
154c0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
154d0 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20  .** with either 
154e0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
154f0 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49  EMSYS3] or [SQLI
15500 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
15510 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  5] and returns.*
15520 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
15530 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65   if invoked othe
15540 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65  rwise..** ^There
15550 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
15560 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
15570 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41  ONFIG_HEAP:.** A
15580 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
15590 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
155a0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
155b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
155c0 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
155d0 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
155e0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
155f0 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
15600 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
15610 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
15620 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
15630 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
15640 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
15650 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
15660 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
15670 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
15680 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
15690 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
156a0 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
156b0 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
156c0 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
156d0 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
156e0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
156f0 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  L then the alter
15700 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
15710 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
15720 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
15730 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
15740 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15750 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
15760 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
15770 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
15780 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
15790 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
157a0 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
157b0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
157c0 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
157d0 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
157e0 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
157f0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
15800 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
15810 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
15820 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
15830 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
15840 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
15850 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
15860 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15870 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
15880 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15890 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
158a0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
158b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
158c0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
158d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
158e0 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69  hich is a.** poi
158f0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
15900 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15910 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15920 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
15930 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
15940 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74  ecifies alternat
15950 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
15960 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
15970 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c  be used.** in pl
15980 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f  ace the mutex ro
15990 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
159a0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
159b0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
159c0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
159d0 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
159e0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
159f0 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
15a00 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
15a10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
15a20 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
15a30 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
15a40 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
15a50 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
15a60 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
15a70 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
15a80 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15a90 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
15aa0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
15ab0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
15ac0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
15ad0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
15ae0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
15af0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
15b00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15b10 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
15b20 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
15b30 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
15b40 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
15b50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15b60 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
15b70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15b80 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
15b90 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
15ba0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15bb0 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
15bc0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15bd0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
15be0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
15bf0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
15c00 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
15c10 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
15c20 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
15c30 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15c40 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
15c50 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
15c60 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
15c70 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
15c80 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
15c90 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
15ca0 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
15cb0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
15cc0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
15cd0 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
15ce0 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
15cf0 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
15d00 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
15d10 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
15d20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
15d30 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
15d40 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
15d50 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
15d60 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
15d70 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15d80 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
15d90 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
15da0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
15db0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
15dc0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
15dd0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
15de0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
15df0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
15e00 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
15e10 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15e20 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
15e30 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
15e40 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
15e50 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
15e60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15e70 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
15e80 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
15e90 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
15ea0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
15eb0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15ec0 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  IDE option takes
15ed0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
15ee0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hat determine.**
15ef0 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a   the default siz
15f00 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  e of lookaside m
15f10 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64  emory on each [d
15f20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15f30 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
15f40 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
15f50 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
15f60 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
15f70 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
15f80 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
15f90 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
15fa0 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
15fb0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
15fc0 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c  ection.)^  ^(SQL
15fd0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
15fe0 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65  SIDE.** sets the
15ff0 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
16000 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
16010 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
16020 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
16030 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71  ** option to [sq
16040 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16050 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
16060 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
16070 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
16080 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
16090 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
160a0 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
160b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
160c0 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
160d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
160e0 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
160f0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
16100 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
16110 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16120 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
16130 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
16140 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
16150 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
16160 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
16170 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
16180 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66  es.** the interf
16190 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  ace to a custom 
161a0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
161b0 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  mentation.)^.** 
161c0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
161d0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
161e0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
161f0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64  ods2] object.</d
16200 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16210 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16220 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
16230 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
16240 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
16250 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
16260 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f  FIG_GETPCACHE2 o
16270 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
16280 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
16290 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
162a0 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
162b0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
162c0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
162d0 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a  ite copies of.**
162e0 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67   the current pag
162f0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
16300 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
16310 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
16320 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16330 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
16340 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
16350 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
16360 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16370 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20  G_LOG option is 
16380 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
16390 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  e the SQLite.** 
163a0 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f  global [error lo
163b0 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c  g]..** (^The SQL
163c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
163d0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
163e0 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
163f0 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
16400 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
16410 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
16420 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
16430 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
16440 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
16450 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
16460 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
16470 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
16480 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
16490 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
164a0 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
164b0 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
164c0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
164d0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
164e0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
164f0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
16500 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
16510 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
16520 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
16530 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
16540 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
16550 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
16560 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
16570 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
16580 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16590 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
165a0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
165b0 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
165c0 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
165d0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
165e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
165f0 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
16600 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
16610 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
16620 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
16630 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
16640 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
16650 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
16660 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
16670 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
16680 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
16690 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
166a0 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
166b0 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
166c0 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
166d0 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
166e0 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
166f0 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
16700 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
16710 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
16720 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
16730 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
16740 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
16750 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
16760 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
16770 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
16780 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
16790 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
167a0 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
167b0 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
167c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
167d0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
167e0 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
167f0 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
16800 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16810 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
16820 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
16830 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49  * <dd>^(The SQLI
16840 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70  TE_CONFIG_URI op
16850 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16860 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
16870 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20  type int..** If 
16880 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55  non-zero, then U
16890 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
168a0 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e  lobally enabled.
168b0 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
168c0 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68  r is zero,.** th
168d0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
168e0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
168f0 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20  bled.)^ ^If URI 
16900 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16910 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c  ally.** enabled,
16920 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70   all filenames p
16930 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
16940 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
16950 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a  te3_open_v2()],.
16960 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
16970 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
16980 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
16990 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
169a0 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
169b0 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
169c0 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
169d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
169e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
169f0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
16a00 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
16a10 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
16a20 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
16a30 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
16a40 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
16a50 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
16a60 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
16a70 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
16a80 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
16a90 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
16aa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16ab0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
16ac0 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
16ad0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16ae0 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
16af0 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
16b00 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
16b10 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
16b20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
16b30 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
16b40 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
16b50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16b60 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16b70 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
16b80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
16b90 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16ba0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
16bb0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
16bc0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f  ING_INDEX_SCAN o
16bd0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
16be0 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20  ngle integer.** 
16bf0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
16c00 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
16c10 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
16c20 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
16c30 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
16c40 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
16c50 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
16c60 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
16c70 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
16c80 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  zer..** ^The def
16c90 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20  ault setting is 
16ca0 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79  determined.** by
16cb0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c   the [SQLITE_ALL
16cc0 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  OW_COVERING_INDE
16cd0 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d  X_SCAN] compile-
16ce0 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20  time option, or 
16cf0 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68  is "on".** if th
16d00 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
16d10 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  option is omitte
16d20 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74  d..** The abilit
16d30 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  y to disable the
16d40 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
16d50 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
16d60 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a  l table scans.**
16d70 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65   is because some
16d80 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64   incorrectly cod
16d90 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63  ed legacy applic
16da0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c  ations might mal
16db0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e  function.** when
16dc0 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
16dd0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50  n is enabled.  P
16de0 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69  roviding the abi
16df0 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62  lity to.** disab
16e00 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  le the optimizat
16e10 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f  ion allows the o
16e20 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c  lder, buggy appl
16e30 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20  ication code to 
16e40 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20  work.** without 
16e50 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68  change even with
16e60 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
16e70 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
16e80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16e90 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49  _PCACHE]] [[SQLI
16ea0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
16eb0 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  CHE]].** <dt>SQL
16ec0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16ed0 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e  E and SQLITE_CON
16ee0 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  FIG_GETPCACHE.**
16ef0 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
16f00 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
16f10 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
16f20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
16f30 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
16f40 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
16f50 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
16f60 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
16f70 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
16f80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16f90 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d  E_CONFIG_SQLLOG]
16fa0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16fb0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a  CONFIG_SQLLOG.**
16fc0 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
16fd0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
16fe0 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20  le if sqlite is 
16ff0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
17000 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
17010 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d  BLE_SQLLOG] pre-
17020 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
17030 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72  defined. The fir
17040 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  st argument shou
17050 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74  ld.** be a point
17060 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  er to a function
17070 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29   of type void(*)
17080 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
17090 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
170a0 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
170b0 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79   should be of ty
170c0 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20  pe (void*). The 
170d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
170e0 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61  ked by the libra
170f0 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73  ry.** in three s
17100 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74  eparate circumst
17110 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65  ances, identifie
17120 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70  d by the value p
17130 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
17140 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
17150 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  . If the fourth 
17160 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20  parameter is 0, 
17170 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
17180 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
17190 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
171a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61  cond argument ha
171b0 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e  s just been open
171c0 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  ed. The third ar
171d0 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73  gument.** points
171e0 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e   to a buffer con
171f0 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65  taining the name
17200 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74   of the main dat
17210 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74  abase file. If t
17220 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
17230 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65  ameter is 1, the
17240 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
17250 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69  ent that the thi
17260 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
17270 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75  points to has ju
17280 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64  st been executed
17290 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75  . Or, if the fou
172a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
172b0 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   2, then.** the 
172c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67  connection being
172d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
172e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
172f0 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e  is being closed.
17300 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   The.** third pa
17310 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65  rameter is passe
17320 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63  d NULL In this c
17330 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ase.  An example
17340 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a   of using this.*
17350 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
17360 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65  option can be se
17370 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f  en in the "test_
17380 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65  sqllog.c" source
17390 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20   file in.** the 
173a0 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65  canonical SQLite
173b0 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64   source tree.</d
173c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
173d0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
173e0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
173f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
17400 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49  IZE.** <dd>^SQLI
17410 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
17420 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
17430 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
17440 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
17450 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
17460 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
17470 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
17480 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
17490 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
174a0 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
174b0 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
174c0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
174d0 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  mit..** ^The def
174e0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e  ault setting can
174f0 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62   be overridden b
17500 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  y each database 
17510 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
17520 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b  .** either the [
17530 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
17540 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79  ] command, or by
17550 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
17560 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
17570 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
17580 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69  rol.  ^(The maxi
17590 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
175a0 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65   size.** will be
175b0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
175c0 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79  ted if necessary
175d0 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73   so that it does
175e0 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a   not exceed the.
175f0 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
17600 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a  maximum mmap siz
17610 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  e set by the.** 
17620 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50  [SQLITE_MAX_MMAP
17630 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SIZE] compile-t
17640 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a  ime option.)^.**
17650 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75   ^If either argu
17660 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74  ment to this opt
17670 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ion is negative,
17680 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d   then that argum
17690 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65  ent is.** change
176a0 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65  d to its compile
176b0 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a  -time default..*
176c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
176d0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
176e0 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
176f0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17700 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64  _HEAPSIZE.** <dd
17710 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17720 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17730 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  ZE option is onl
17740 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
17750 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
17760 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73  iled for Windows
17770 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
17780 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20  E_WIN32_MALLOC] 
17790 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
177a0 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20  cro.** defined. 
177b0 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  ^SQLITE_CONFIG_W
177c0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
177d0 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
177e0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
177f0 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
17800 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
17810 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
17820 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a  eated heap..**.*
17830 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17840 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d  G_PCACHE_HDRSZ]]
17850 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17860 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
17870 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
17880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17890 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e  CHE_HDRSZ option
178a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
178b0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
178c0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
178d0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
178e0 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68  d writes into th
178f0 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e  at integer the n
17900 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a  umber of extra.*
17910 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65  * bytes per page
17920 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61   required for ea
17930 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49  ch page in [SQLI
17940 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
17950 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f  CHE]..** The amo
17960 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61  unt of extra spa
17970 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20  ce required can 
17980 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67  change depending
17990 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72   on the compiler
179a0 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74  ,.** target plat
179b0 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65  form, and SQLite
179c0 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20   version..**.** 
179d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
179e0 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PMASZ]].** <dt>S
179f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17a00 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
17a10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17a20 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
17a30 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
17a40 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
17a50 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  n unsigned integ
17a60 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20  er and sets the 
17a70 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a  "Minimum PMA Siz
17a80 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69  e" for the multi
17a90 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74  threaded.** sort
17aa0 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67  er to that integ
17ab0 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  er.  The default
17ac0 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a   minimum PMA Siz
17ad0 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a  e is set by the.
17ae0 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45  ** [SQLITE_SORTE
17af0 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65  R_PMASZ] compile
17b00 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e  -time option.  N
17b10 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c  ew threads are l
17b20 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65  aunched.** to he
17b30 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65  lp with sort ope
17b40 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c  rations when mul
17b50 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69  tithreaded sorti
17b60 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64  ng.** is enabled
17b70 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41   (using the [PRA
17b80 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d  GMA threads] com
17b90 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d  mand) and the am
17ba0 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a  ount of content.
17bb0 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20  ** to be sorted 
17bc0 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65  exceeds the page
17bd0 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20   size times the 
17be0 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a  minimum of the.*
17bf0 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f  * [PRAGMA cache_
17c00 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e  size] setting an
17c10 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a  d this value..**
17c20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17c30 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
17c40 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  LL]].** <dt>SQLI
17c50 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
17c60 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e  NL_SPILL.** <dd>
17c70 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
17c80 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
17c90 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  L option takes a
17ca0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
17cb0 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d  r which.** becom
17cc0 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e  es the [statemen
17cd0 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c  t journal] spill
17ce0 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f  -to-disk thresho
17cf0 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d  ld.  .** [Statem
17d00 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72  ent journals] ar
17d10 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  e held in memory
17d20 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a   until their siz
17d30 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20  e (in bytes).** 
17d40 65 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72  exceeds this thr
17d50 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68  eshold, at which
17d60 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20   point they are 
17d70 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e  written to disk.
17d80 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68  .** Or if the th
17d90 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73  reshold is -1, s
17da0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
17db0 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c  s are always hel
17dc0 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79  d.** exclusively
17dd0 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   in memory..** S
17de0 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d  ince many statem
17df0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76  ent journals nev
17e00 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c  er become large,
17e10 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69   setting the spi
17e20 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20  ll.** threshold 
17e30 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20  to a value such 
17e40 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65  as 64KiB can gre
17e50 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20  atly reduce the 
17e60 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f  amount of.** I/O
17e70 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70   required to sup
17e80 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72  port statement r
17e90 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  ollback..** The 
17ea0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f  default value fo
17eb0 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  r this setting i
17ec0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
17ed0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  the.** [SQLITE_S
17ee0 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63  TMTJRNL_SPILL] c
17ef0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17f00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
17f10 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52  TE_CONFIG_SORTER
17f20 52 45 46 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  REF_SIZE]].** <d
17f30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17f40 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 0a 2a  SORTERREF_SIZE.*
17f50 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
17f60 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45  _CONFIG_SORTERRE
17f70 46 5f 53 49 5a 45 20 6f 70 74 69 6f 6e 20 61 63  F_SIZE option ac
17f80 63 65 70 74 73 20 61 20 73 69 6e 67 6c 65 20 70  cepts a single p
17f90 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6f 66 20 74  arameter.** of t
17fa0 79 70 65 20 28 69 6e 74 29 20 2d 20 74 68 65 20  ype (int) - the 
17fb0 6e 65 77 20 76 61 6c 75 65 20 6f 66 20 74 68 65  new value of the
17fc0 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63   sorter-referenc
17fd0 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64  e size threshold
17fe0 2e 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 77 68  ..** Usually, wh
17ff0 65 6e 20 53 51 4c 69 74 65 20 75 73 65 73 20 61  en SQLite uses a
18000 6e 20 65 78 74 65 72 6e 61 6c 20 73 6f 72 74 20  n external sort 
18010 74 6f 20 6f 72 64 65 72 20 72 65 63 6f 72 64 73  to order records
18020 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f   according.** to
18030 20 61 6e 20 4f 52 44 45 52 20 42 59 20 63 6c 61   an ORDER BY cla
18040 75 73 65 2c 20 61 6c 6c 20 66 69 65 6c 64 73 20  use, all fields 
18050 72 65 71 75 69 72 65 64 20 62 79 20 74 68 65 20  required by the 
18060 63 61 6c 6c 65 72 20 61 72 65 20 70 72 65 73 65  caller are prese
18070 6e 74 20 69 6e 20 74 68 65 0a 2a 2a 20 73 6f 72  nt in the.** sor
18080 74 65 64 20 72 65 63 6f 72 64 73 2e 20 48 6f 77  ted records. How
18090 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
180a0 64 65 74 65 72 6d 69 6e 65 73 20 62 61 73 65 64  determines based
180b0 20 6f 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64   on the declared
180c0 20 74 79 70 65 0a 2a 2a 20 6f 66 20 61 20 74 61   type.** of a ta
180d0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
180e0 69 74 73 20 76 61 6c 75 65 73 20 61 72 65 20 6c  its values are l
180f0 69 6b 65 6c 79 20 74 6f 20 62 65 20 76 65 72 79  ikely to be very
18100 20 6c 61 72 67 65 20 2d 20 6c 61 72 67 65 72 0a   large - larger.
18110 2a 2a 20 74 68 61 6e 20 74 68 65 20 63 6f 6e 66  ** than the conf
18120 69 67 75 72 65 64 20 73 6f 72 74 65 72 2d 72 65  igured sorter-re
18130 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68 72  ference size thr
18140 65 73 68 6f 6c 64 20 2d 20 74 68 65 6e 20 61 20  eshold - then a 
18150 72 65 66 65 72 65 6e 63 65 0a 2a 2a 20 69 73 20  reference.** is 
18160 73 74 6f 72 65 64 20 69 6e 20 65 61 63 68 20 73  stored in each s
18170 6f 72 74 65 64 20 72 65 63 6f 72 64 20 61 6e 64  orted record and
18180 20 74 68 65 20 72 65 71 75 69 72 65 64 20 63 6f   the required co
18190 6c 75 6d 6e 20 76 61 6c 75 65 73 20 6c 6f 61 64  lumn values load
181a0 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 64  ed.** from the d
181b0 61 74 61 62 61 73 65 20 61 73 20 72 65 63 6f 72  atabase as recor
181c0 64 73 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  ds are returned 
181d0 69 6e 20 73 6f 72 74 65 64 20 6f 72 64 65 72 2e  in sorted order.
181e0 20 54 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   The default.** 
181f0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 6f  value for this o
18200 70 74 69 6f 6e 20 69 73 20 74 6f 20 6e 65 76 65  ption is to neve
18210 72 20 75 73 65 20 74 68 69 73 20 6f 70 74 69 6d  r use this optim
18220 69 7a 61 74 69 6f 6e 2e 20 53 70 65 63 69 66 79  ization. Specify
18230 69 6e 67 20 61 20 0a 2a 2a 20 6e 65 67 61 74 69  ing a .** negati
18240 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  ve value for thi
18250 73 20 6f 70 74 69 6f 6e 20 72 65 73 74 6f 72 65  s option restore
18260 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 62 65  s the default be
18270 68 61 76 69 6f 75 72 2e 0a 2a 2a 20 54 68 69 73  haviour..** This
18280 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
18290 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
182a0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
182b0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
182c0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 4f 52 54 45  ITE_ENABLE_SORTE
182d0 52 5f 52 45 46 45 52 45 4e 43 45 53 5d 20 63 6f  R_REFERENCES] co
182e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
182f0 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  n..** </dl>.*/.#
18300 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18310 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
18320 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
18330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18340 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
18350 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
18360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18370 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
18380 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
18390 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
183a0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
183b0 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
183c0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
183d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
183e0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
183f0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
18400 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
18410 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
18420 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
18430 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
18440 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
18450 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18460 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
18470 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
18480 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
18490 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
184a0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
184b0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
184c0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
184d0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
184e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
184f0 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
18500 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
18510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18520 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
18530 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
18540 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
18550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18560 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
18570 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
18580 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
18590 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
185a0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
185b0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
185c0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
185d0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
185e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
185f0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
18600 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
18610 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18620 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
18630 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
18640 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18650 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
18660 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
18670 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
18680 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
18690 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
186a0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
186b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
186c0 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
186d0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
186e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
186f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
18700 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
18710 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
18720 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
18730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18740 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
18750 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
18760 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
18770 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18780 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
18790 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
187a0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
187b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
187c0 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
187d0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
187e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
187f0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
18800 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
18810 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
18820 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
18830 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18840 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
18850 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
18860 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
18870 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
18880 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
18890 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
188a0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
188b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
188c0 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
188d0 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
188e0 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65  int szPma */.#de
188f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18900 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
18910 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e  L      26  /* in
18920 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
18930 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18940 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 20 20  _SMALL_MALLOC   
18950 20 20 20 20 20 32 37 20 20 2f 2a 20 62 6f 6f 6c       27  /* bool
18960 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
18970 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52  QLITE_CONFIG_SOR
18980 54 45 52 52 45 46 5f 53 49 5a 45 20 20 20 20 20  TERREF_SIZE     
18990 20 32 38 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   28  /* int nByt
189a0 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e */../*.** CAPI
189b0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
189c0 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
189d0 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
189e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
189f0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
18a00 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
18a10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
18a20 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
18a30 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
18a40 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18a50 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
18a60 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
18a70 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
18a80 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
18a90 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
18aa0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
18ab0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
18ac0 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
18ad0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
18ae0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
18af0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
18b00 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
18b10 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
18b20 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
18b30 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
18b40 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
18b50 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
18b60 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
18b70 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
18b80 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
18b90 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
18ba0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
18bb0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
18bc0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
18bd0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
18be0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
18bf0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
18c00 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
18c10 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18c20 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
18c30 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
18c40 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
18c50 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
18c60 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
18c70 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
18c80 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
18c90 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
18ca0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
18cb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18cc0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
18cd0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
18ce0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
18cf0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
18d00 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
18d10 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
18d20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
18d30 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
18d40 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
18d50 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
18d60 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
18d70 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
18d80 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
18d90 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
18da0 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
18db0 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
18dc0 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
18dd0 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
18de0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
18df0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
18e00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
18e10 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
18e20 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
18e30 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
18e40 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
18e50 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
18e60 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
18e70 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
18e80 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
18e90 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
18ea0 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
18eb0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
18ec0 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
18ed0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
18ee0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
18ef0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
18f00 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
18f10 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
18f20 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
18f30 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
18f40 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18f50 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
18f60 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
18f70 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
18f80 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
18f90 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
18fa0 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
18fb0 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
18fc0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
18fd0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
18fe0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
18ff0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
19000 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
19010 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
19020 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
19030 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
19040 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
19050 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
19060 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
19070 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
19080 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
19090 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
190a0 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
190b0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
190c0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
190d0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
190e0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
190f0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
19100 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
19110 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
19120 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
19130 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
19140 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
19150 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
19160 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
19170 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
19180 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19190 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
191a0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
191b0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
191c0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
191d0 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
191e0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
191f0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
19200 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
19210 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19220 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
19230 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19240 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
19250 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
19260 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
19270 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
19280 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
19290 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
192a0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
192b0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
192c0 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
192d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
192e0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
192f0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
19300 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
19310 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
19320 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
19330 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
19340 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
19350 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
19360 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
19370 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
19380 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
19390 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
193a0 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
193b0 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
193c0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
193d0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
193e0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
193f0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
19400 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
19410 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
19420 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
19430 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
19440 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
19450 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
19460 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
19470 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
19480 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
19490 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
194a0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
194b0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
194c0 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
194d0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
194e0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
194f0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
19500 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
19510 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
19520 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19530 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19540 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19550 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19560 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19570 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
19580 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
19590 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
195a0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
195b0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
195c0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
195d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
195e0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
195f0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
19600 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
19610 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
19620 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
19630 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19640 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
19650 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19660 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19670 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
19680 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d  disable the two-
19690 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73  argument.** vers
196a0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33  ion of the [fts3
196b0 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75  _tokenizer()] fu
196c0 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20  nction which is 
196d0 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  part of the.** [
196e0 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20  FTS3] full-text 
196f0 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78  search engine ex
19700 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72  tension..** Ther
19710 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
19720 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
19730 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
19740 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
19750 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
19760 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
19770 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
19780 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20   or.** positive 
19790 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74  to enable fts3_t
197a0 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65  okenizer() or ne
197b0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
197c0 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  the setting.** u
197d0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
197e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
197f0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
19800 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
19810 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
19820 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
19830 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
19840 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20   fts3_tokenizer 
19850 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
19860 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
19870 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
19880 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19890 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
198a0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
198b0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
198c0 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
198d0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
198e0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
198f0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19900 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
19910 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a  XTENSION</dt>.**
19920 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
19930 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
19940 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
19950 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
19960 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
19970 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65  * interface inde
19980 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65  pendently of the
19990 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
199a0 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
199b0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
199c0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
199d0 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65  tension()] API e
199e0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
199f0 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43  es both the.** C
19a00 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  -API [sqlite3_lo
19a10 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
19a20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
19a30 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e  tion [load_exten
19a40 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72  sion()]..** Ther
19a50 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
19a60 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
19a70 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  ents..** When th
19a80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19a90 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61   to this interfa
19aa0 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e  ce is 1, then on
19ab0 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a  ly the C-API is.
19ac0 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74  ** enabled and t
19ad0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
19ae0 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64  remains disabled
19af0 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
19b00 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
19b10 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
19b20 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68   0, then both th
19b30 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20  e C-API and the 
19b40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  SQL function are
19b50 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66   disabled..** If
19b60 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
19b70 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ent is -1, then 
19b80 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d  no changes are m
19b90 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20  ade to state of 
19ba0 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d  either the.** C-
19bb0 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66  API or the SQL f
19bc0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
19bd0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19be0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
19bf0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
19c00 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
19c10 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
19c20 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
19c30 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
19c40 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72  tension()] inter
19c50 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62  face.** is disab
19c60 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66  led or enabled f
19c70 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
19c80 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
19c90 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a  parameter may.**
19ca0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
19cb0 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  er, in which cas
19cc0 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
19cd0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
19ce0 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e  d back..** </dd>
19cf0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
19d00 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
19d10 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BNAME</dt>.** <d
19d20 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
19d30 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  is used to chang
19d40 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
19d50 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73  e "main" databas
19d60 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54  e.** schema.  ^T
19d70 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74  he sole argument
19d80 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
19d90 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38   a constant UTF8
19da0 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68   string.** which
19db0 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
19dc0 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65   new schema name
19dd0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61   in place of "ma
19de0 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a  in".  ^SQLite.**
19df0 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61   does not make a
19e00 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77   copy of the new
19e10 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d   main schema nam
19e20 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65  e string, so the
19e30 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
19e40 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
19e50 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61   the argument pa
19e60 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44  ssed into this D
19e70 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69  BCONFIG option i
19e80 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75  s unchanged.** u
19e90 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64  ntil after the d
19ea0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19eb0 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f  on closes..** </
19ec0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
19ed0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
19ee0 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f  _CKPT_ON_CLOSE</
19ef0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61  dt>.** <dd> Usua
19f00 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61  lly, when a data
19f10 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65  base in wal mode
19f20 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65   is closed or de
19f30 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a  tached from a .*
19f40 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * database handl
19f50 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73  e, SQLite checks
19f60 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65   if this will me
19f70 61 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72  an that there ar
19f80 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e  e now no .** con
19f90 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20  nections at all 
19fa0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  to the database.
19fb0 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f   If so, it perfo
19fc0 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74  rms a checkpoint
19fd0 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62   .** operation b
19fe0 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68  efore closing th
19ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68  e connection. Th
1a000 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65  is option may be
1a010 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72   used to.** over
1a020 72 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69  ride this behavi
1a030 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70  our. The first p
1a040 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
1a050 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f  to this operatio
1a060 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67  n.** is an integ
1a070 65 72 20 2d 20 70 6f 73 69 74 69 76 65 20 74 6f  er - positive to
1a080 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f   disable checkpo
1a090 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f  ints-on-close, o
1a0a0 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64  r zero (the.** d
1a0b0 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c  efault) to enabl
1a0c0 65 20 74 68 65 6d 2c 20 61 6e 64 20 6e 65 67 61  e them, and nega
1a0d0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1a0e0 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
1a0f0 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
1a100 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1a110 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1a120 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20  integer.** into 
1a130 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e  which is written
1a140 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
1a150 61 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63  ate whether chec
1a160 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65  kpoints-on-close
1a170 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69  .** have been di
1a180 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68  sabled - 0 if th
1a190 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62  ey are not disab
1a1a0 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61  led, 1 if they a
1a1b0 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  re..** </dd>.**.
1a1c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
1a1d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50  CONFIG_ENABLE_QP
1a1e0 53 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  SG</dt>.** <dd>^
1a1f0 28 54 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  (The SQLITE_DBCO
1a200 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47  NFIG_ENABLE_QPSG
1a210 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65   option activate
1a220 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73  s or deactivates
1a230 0a 2a 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70  .** the [query p
1a240 6c 61 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79  lanner stability
1a250 20 67 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53   guarantee] (QPS
1a260 47 29 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50  G).  When the QP
1a270 53 47 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a  SG is active,.**
1a280 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75   a single SQL qu
1a290 65 72 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ery statement wi
1a2a0 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68  ll always use th
1a2b0 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
1a2c0 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
1a2d0 66 20 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75  f values of [bou
1a2e0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  nd parameters].)
1a2f0 5e 20 54 68 65 20 51 50 53 47 20 64 69 73 61 62  ^ The QPSG disab
1a300 6c 65 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f  les some query o
1a310 70 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20  ptimizations.** 
1a320 74 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65  that look at the
1a330 20 76 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64   values of bound
1a340 20 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69   parameters, whi
1a350 63 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65  ch can make some
1a360 20 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77   queries.** slow
1a370 65 72 2e 20 20 42 75 74 20 74 68 65 20 51 50 53  er.  But the QPS
1a380 47 20 68 61 73 20 74 68 65 20 61 64 76 61 6e 74  G has the advant
1a390 61 67 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64  age of more pred
1a3a0 69 63 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72  ictable behavior
1a3b0 2e 20 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51  .  With.** the Q
1a3c0 50 53 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69  PSG active, SQLi
1a3d0 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75  te will always u
1a3e0 73 65 20 74 68 65 20 73 61 6d 65 20 71 75 65 72  se the same quer
1a3f0 79 20 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69  y plan in the fi
1a400 65 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73  eld as.** was us
1a410 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
1a420 67 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a  g in the lab..**
1a430 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1a440 65 6e 74 20 74 6f 20 74 68 69 73 20 73 65 74 74  ent to this sett
1a450 69 6e 67 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ing is an intege
1a460 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
1a470 64 69 73 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20  disable .** the 
1a480 51 50 53 47 2c 20 70 6f 73 69 74 69 76 65 20 74  QPSG, positive t
1a490 6f 20 65 6e 61 62 6c 65 20 51 50 53 47 2c 20 6f  o enable QPSG, o
1a4a0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
1a4b0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a  ave the setting.
1a4c0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 54 68  ** unchanged. Th
1a4d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a4e0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
1a4f0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
1a500 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
1a510 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
1a520 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
1a530 72 20 74 68 65 20 51 50 53 47 20 69 73 20 64 69  r the QPSG is di
1a540 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
1a550 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
1a560 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64  his call..** </d
1a570 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1a580 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49  ITE_DBCONFIG_TRI
1a590 47 47 45 52 5f 45 51 50 3c 2f 64 74 3e 0a 2a 2a  GGER_EQP</dt>.**
1a5a0 20 3c 64 64 3e 20 42 79 20 64 65 66 61 75 6c 74   <dd> By default
1a5b0 2c 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  , the output of 
1a5c0 45 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c  EXPLAIN QUERY PL
1a5d0 41 4e 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 65 73  AN commands does
1a5e0 20 6e 6f 74 20 0a 2a 2a 20 69 6e 63 6c 75 64 65   not .** include
1a5f0 20 6f 75 74 70 75 74 20 66 6f 72 20 61 6e 79 20   output for any 
1a600 6f 70 65 72 61 74 69 6f 6e 73 20 70 65 72 66 6f  operations perfo
1a610 72 6d 65 64 20 62 79 20 74 72 69 67 67 65 72 20  rmed by trigger 
1a620 70 72 6f 67 72 61 6d 73 2e 20 54 68 69 73 0a 2a  programs. This.*
1a630 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1a640 20 74 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72   to set or clear
1a650 20 28 74 68 65 20 64 65 66 61 75 6c 74 29 20 61   (the default) a
1a660 20 66 6c 61 67 20 74 68 61 74 20 67 6f 76 65 72   flag that gover
1a670 6e 73 20 74 68 69 73 0a 2a 2a 20 62 65 68 61 76  ns this.** behav
1a680 69 6f 72 2e 20 54 68 65 20 66 69 72 73 74 20 70  ior. The first p
1a690 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
1a6a0 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f  to this operatio
1a6b0 6e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  n is an integer 
1a6c0 2d 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  -.** positive to
1a6d0 20 65 6e 61 62 6c 65 20 6f 75 74 70 75 74 20 66   enable output f
1a6e0 6f 72 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  or trigger progr
1a6f0 61 6d 73 2c 20 6f 72 20 7a 65 72 6f 20 74 6f 20  ams, or zero to 
1a700 64 69 73 61 62 6c 65 20 69 74 2c 0a 2a 2a 20 6f  disable it,.** o
1a710 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
1a720 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
1a730 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
1a740 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a750 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
1a760 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
1a770 74 6f 20 77 68 69 63 68 20 69 73 20 77 72 69 74  to which is writ
1a780 74 65 6e 20 0a 2a 2a 20 30 20 6f 72 20 31 20 74  ten .** 0 or 1 t
1a790 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
1a7a0 65 72 20 6f 75 74 70 75 74 2d 66 6f 72 2d 74 72  er output-for-tr
1a7b0 69 67 67 65 72 73 20 68 61 73 20 62 65 65 6e 20  iggers has been 
1a7c0 64 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20  disabled - 0 if 
1a7d0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 64 69  .** it is not di
1a7e0 73 61 62 6c 65 64 2c 20 31 20 69 66 20 69 74 20  sabled, 1 if it 
1a7f0 69 73 2e 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  is.  .** </dd>.*
1a800 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a810 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44  DBCONFIG_RESET_D
1a820 41 54 41 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20  ATABASE</dt>.** 
1a830 3c 64 64 3e 20 53 65 74 20 74 68 65 20 53 51 4c  <dd> Set the SQL
1a840 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1a850 45 54 5f 44 41 54 41 42 41 53 45 20 66 6c 61 67  ET_DATABASE flag
1a860 20 61 6e 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a   and then run.**
1a870 20 5b 56 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64   [VACUUM] in ord
1a880 65 72 20 74 6f 20 72 65 73 65 74 20 61 20 64 61  er to reset a da
1a890 74 61 62 61 73 65 20 62 61 63 6b 20 74 6f 20 61  tabase back to a
1a8a0 6e 20 65 6d 70 74 79 20 64 61 74 61 62 61 73 65  n empty database
1a8b0 0a 2a 2a 20 77 69 74 68 20 6e 6f 20 73 63 68 65  .** with no sche
1a8c0 6d 61 20 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e  ma and no conten
1a8d0 74 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  t. The following
1a8e0 20 70 72 6f 63 65 73 73 20 77 6f 72 6b 73 20 65   process works e
1a8f0 76 65 6e 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64  ven for.** a bad
1a900 6c 79 20 63 6f 72 72 75 70 74 65 64 20 64 61 74  ly corrupted dat
1a910 61 62 61 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c  abase file:.** <
1a920 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74  ol>.** <li> If t
1a930 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a940 65 63 74 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20  ection is newly 
1a950 6f 70 65 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72  opened, make sur
1a960 65 20 69 74 20 68 61 73 20 72 65 61 64 20 74 68  e it has read th
1a970 65 0a 2a 2a 20 20 20 20 20 20 64 61 74 61 62 61  e.**      databa
1a980 73 65 20 73 63 68 65 6d 61 20 62 79 20 70 72 65  se schema by pre
1a990 70 61 72 69 6e 67 20 74 68 65 6e 20 64 69 73 63  paring then disc
1a9a0 61 72 64 69 6e 67 20 73 6f 6d 65 20 71 75 65 72  arding some quer
1a9b0 79 20 61 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a  y against the.**
1a9c0 20 20 20 20 20 20 64 61 74 61 62 61 73 65 2c 20        database, 
1a9d0 6f 72 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  or calling sqlit
1a9e0 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
1a9f0 6d 65 74 61 64 61 74 61 28 29 2c 20 69 67 6e 6f  metadata(), igno
1aa00 72 69 6e 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20  ring any.**     
1aa10 20 65 72 72 6f 72 73 2e 20 20 54 68 69 73 20 73   errors.  This s
1aa20 74 65 70 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65  tep is only nece
1aa30 73 73 61 72 79 20 69 66 20 74 68 65 20 61 70 70  ssary if the app
1aa40 6c 69 63 61 74 69 6f 6e 20 64 65 73 69 72 65 73  lication desires
1aa50 20 74 6f 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20   to keep.**     
1aa60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
1aa70 20 57 41 4c 20 6d 6f 64 65 20 61 66 74 65 72 20   WAL mode after 
1aa80 74 68 65 20 72 65 73 65 74 20 69 66 20 69 74 20  the reset if it 
1aa90 77 61 73 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20  was in WAL mode 
1aaa0 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74  before.**      t
1aab0 68 65 20 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c  he reset.  .** <
1aac0 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  li> sqlite3_db_c
1aad0 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 54 45  onfig(db, SQLITE
1aae0 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1aaf0 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30 29 3b  DATABASE, 1, 0);
1ab00 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  .** <li> [sqlite
1ab10 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b 56 41  3_exec](db, "[VA
1ab20 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29  CUUM]", 0, 0, 0)
1ab30 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  ;.** <li> sqlite
1ab40 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20  3_db_config(db, 
1ab50 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1ab60 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c 20  RESET_DATABASE, 
1ab70 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  0, 0);.** </ol>.
1ab80 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73 65 74  ** Because reset
1ab90 74 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  ting a database 
1aba0 69 73 20 64 65 73 74 72 75 63 74 69 76 65 20 61  is destructive a
1abb0 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c 65 2c  nd irreversible,
1abc0 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20   the.** process 
1abd0 72 65 71 75 69 72 65 73 20 74 68 65 20 75 73 65  requires the use
1abe0 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75 72 65   of this obscure
1abf0 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c   API and multipl
1ac00 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c 70 0a  e steps to help.
1ac10 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74 20 69  ** ensure that i
1ac20 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70 70 65  t does not happe
1ac30 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a  n by accident..*
1ac40 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  * </dd>.** </dl>
1ac50 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1ac60 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
1ac70 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  DBNAME          
1ac80 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20    1000 /* const 
1ac90 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  char* */.#define
1aca0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1acb0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
1acc0 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76         1001 /* v
1acd0 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
1ace0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1acf0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
1ad00 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30  KEY           10
1ad10 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  02 /* int int* *
1ad20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ad30 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1ad40 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1ad50 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1003 /* int int*
1ad60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ad70 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1ad80 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
1ad90 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e  R 1004 /* int in
1ada0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1adb0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1adc0 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
1add0 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20  ION 1005 /* int 
1ade0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1adf0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1ae00 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
1ae10 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e        1006 /* in
1ae20 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1ae30 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1ae40 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20  G_ENABLE_QPSG   
1ae50 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20          1007 /* 
1ae60 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1ae70 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1ae80 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20  FIG_TRIGGER_EQP 
1ae90 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20 2f            1008 /
1aea0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1aeb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1aec0 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1aed0 42 41 53 45 20 20 20 20 20 20 20 20 31 30 30 39  BASE        1009
1aee0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1aef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1af00 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20 20  BCONFIG_MAX     
1af10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30                10
1af20 30 39 20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42  09 /* Largest DB
1af30 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  CONFIG */../*.**
1af40 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
1af50 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
1af60 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
1af70 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1af80 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1af90 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1afa0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
1afb0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
1afc0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
1afd0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1afe0 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
1aff0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
1b000 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
1b010 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
1b020 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1b030 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
1b040 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
1b050 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
1b060 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
1b070 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
1b080 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
1b090 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
1b0a0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
1b0b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1b0c0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  te3.**.** ^Each 
1b0d0 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
1b0e0 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
1b0f0 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
1b100 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
1b110 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
1b120 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
1b130 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
1b140 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
1b150 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
1b160 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
1b170 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
1b180 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
1b190 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
1b1a0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
1b1b0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
1b1c0 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
1b1d0 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
1b1e0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
1b1f0 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
1b200 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
1b210 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
1b220 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
1b230 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
1b240 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
1b250 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
1b260 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
1b270 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b280 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1b290 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
1b2a0 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  usually returns 
1b2b0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a  the [rowid] of.*
1b2c0 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  * the most recen
1b2d0 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
1b2e0 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
1b2f0 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
1b300 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
1b310 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
1b320 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74  ction D. ^Insert
1b330 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20  s into [WITHOUT 
1b340 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72  ROWID] tables ar
1b350 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65  e not.** recorde
1b360 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  d. ^If no succes
1b370 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69  sful [INSERT]s i
1b380 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
1b390 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
1b3a0 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64  red .** on the d
1b3b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b3c0 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74  on D, then sqlit
1b3d0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1b3e0 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
1b3f0 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  .** zero..**.** 
1b400 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67  As well as being
1b410 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c   set automatical
1b420 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69  ly as rows are i
1b430 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74  nserted into dat
1b440 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c  abase.** tables,
1b450 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b460 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
1b470 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20  tion may be set 
1b480 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a  explicitly by.**
1b490 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
1b4a0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1b4b0 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69  )].**.** Some vi
1b4c0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
1b4d0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
1b4e0 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f  INSERT rows into
1b4f0 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73   rowid tables as
1b500 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d  .** part of comm
1b510 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63  itting a transac
1b520 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c  tion (e.g. to fl
1b530 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c  ush data accumul
1b540 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ated in memory.*
1b550 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74  * to disk). In t
1b560 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75  his case subsequ
1b570 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69  ent calls to thi
1b580 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1b590 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61  n the rowid.** a
1b5a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1b5b0 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e  hese internal IN
1b5c0 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c  SERT operations,
1b5d0 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20   which leads to 
1b5e0 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20  .** unintuitive 
1b5f0 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c  results. Virtual
1b600 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
1b610 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77  ations that do w
1b620 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a  rite to rowid.**
1b630 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20   tables in this 
1b640 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68  way can avoid th
1b650 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65  is problem by re
1b660 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67  storing the orig
1b670 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76  inal .** rowid v
1b680 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  alue using [sqli
1b690 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
1b6a0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66  ert_rowid()] bef
1b6b0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a  ore returning .*
1b6c0 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65  * control to the
1b6d0 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   user..**.** ^(I
1b6e0 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
1b6f0 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
1b700 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20  igger then this 
1b710 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a  routine will .**
1b720 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
1b730 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
1b740 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  ted row as long 
1b750 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69  as the trigger i
1b760 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f  s .** running. O
1b770 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
1b780 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68  program ends, th
1b790 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1b7a0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
1b7b0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
1b7c0 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
1b7d0 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77  re the trigger w
1b7e0 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  as fired.)^.**.*
1b7f0 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
1b800 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
1b810 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
1b820 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
1b830 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
1b840 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
1b850 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1b860 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1b870 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
1b880 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
1b890 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
1b8a0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
1b8b0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
1b8c0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
1b8d0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
1b8e0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
1b8f0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1b900 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
1b910 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
1b920 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
1b930 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
1b940 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
1b950 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
1b960 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
1b970 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
1b980 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
1b990 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
1b9a0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
1b9b0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
1b9c0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
1b9d0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
1b9e0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
1b9f0 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
1ba00 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
1ba10 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
1ba20 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
1ba30 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
1ba40 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
1ba50 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
1ba60 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
1ba70 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
1ba80 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
1ba90 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
1baa0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
1bab0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
1bac0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
1bad0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
1bae0 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
1baf0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1bb00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1bb10 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1bb20 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
1bb30 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
1bb40 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
1bb50 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1bb60 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
1bb70 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
1bb80 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
1bb90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
1bba0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
1bbb0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
1bbc0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
1bbd0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
1bbe0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1bbf0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1bc00 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
1bc10 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1bc20 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
1bc30 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
1bc40 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
1bc50 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1bc60 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
1bc70 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
1bc80 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1bc90 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1bca0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1bcb0 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20  the Last Insert 
1bcc0 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20  Rowid value..** 
1bcd0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1bce0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1bcf0 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1bd00 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65  t_rowid(D, R) me
1bd10 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20  thod allows the 
1bd20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a  application to.*
1bd30 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20  * set the value 
1bd40 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c  returned by call
1bd50 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  ing sqlite3_last
1bd60 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
1bd70 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75   to R .** withou
1bd80 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f  t inserting a ro
1bd90 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  w into the datab
1bda0 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ase..*/.void sql
1bdb0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1bdc0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
1bdd0 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  e3*,sqlite3_int6
1bde0 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
1bdf0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
1be00 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1be10 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1be20 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1be30 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1be40 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1be50 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1be60 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
1be70 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
1be80 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
1be90 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
1bea0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1beb0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
1bec0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
1bed0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
1bee0 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
1bef0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1bf00 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1bf10 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1bf20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
1bf30 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
1bf40 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1bf50 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
1bf60 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
1bf70 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
1bf80 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
1bf90 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1bfa0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
1bfb0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
1bfc0 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
1bfd0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
1bfe0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
1bff0 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
1c000 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1c010 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
1c020 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
1c030 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
1c040 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
1c050 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1c060 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1c070 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
1c080 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1c090 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
1c0a0 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
1c0b0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
1c0c0 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
1c0d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1c0e0 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
1c0f0 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
1c100 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
1c110 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
1c120 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
1c130 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
1c140 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
1c150 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
1c160 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
1c170 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
1c180 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
1c190 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
1c1a0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
1c1b0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
1c1c0 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
1c1d0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
1c1e0 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
1c1f0 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
1c200 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
1c210 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1c220 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
1c230 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
1c240 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1c250 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
1c260 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
1c270 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
1c280 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
1c290 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
1c2a0 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
1c2b0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1c2c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1c2d0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1c2e0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1c2f0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
1c300 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
1c310 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
1c320 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
1c330 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
1c340 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
1c350 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
1c360 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
1c370 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1c380 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
1c390 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
1c3a0 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
1c3b0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
1c3c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1c3d0 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
1c3e0 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
1c3f0 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
1c400 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
1c410 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
1c420 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
1c430 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
1c440 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
1c450 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
1c460 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
1c470 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1c480 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
1c490 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
1c4a0 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
1c4b0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
1c4c0 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
1c4d0 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
1c4e0 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
1c4f0 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
1c500 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
1c510 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
1c520 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
1c530 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1c540 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1c550 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1c560 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
1c570 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
1c580 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
1c590 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
1c5a0 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
1c5b0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
1c5c0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
1c5d0 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
1c5e0 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
1c5f0 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
1c600 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
1c610 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
1c620 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
1c630 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
1c640 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
1c650 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
1c660 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1c670 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1c680 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
1c690 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1c6a0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1c6b0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1c6c0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1c6d0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1c6e0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
1c6f0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1c700 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1c710 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
1c720 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1c730 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1c740 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
1c750 6f 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  o:.** <ul>.** <l
1c760 69 3e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  i> the [sqlite3_
1c770 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1c780 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 3c 6c   interface.** <l
1c790 69 3e 20 74 68 65 20 5b 63 6f 75 6e 74 5f 63 68  i> the [count_ch
1c7a0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 0a 2a 2a  anges pragma].**
1c7b0 20 3c 6c 69 3e 20 74 68 65 20 5b 63 68 61 6e 67   <li> the [chang
1c7c0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1c7d0 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  n].** <li> the [
1c7e0 64 61 74 61 5f 76 65 72 73 69 6f 6e 20 70 72 61  data_version pra
1c7f0 67 6d 61 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  gma].** </ul>.*/
1c800 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
1c810 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1c820 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c830 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
1c840 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
1c850 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1c860 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
1c870 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1c880 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
1c890 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64  of rows inserted
1c8a0 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a  , modified or.**
1c8b0 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20   deleted by all 
1c8c0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
1c8d0 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
1c8e0 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65  tatements comple
1c8f0 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ted.** since the
1c900 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c910 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c  tion was opened,
1c920 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65   including those
1c930 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20   executed as.** 
1c940 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20  part of trigger 
1c950 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75  programs. ^Execu
1c960 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
1c970 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
1c980 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ment.** does not
1c990 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75   affect the valu
1c9a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1c9b0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1c9c0 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43  ges()..** .** ^C
1c9d0 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70  hanges made as p
1c9e0 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20  art of [foreign 
1c9f0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
1ca00 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
1ca10 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74  .** count, but t
1ca20 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72  hose made as par
1ca30 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  t of REPLACE con
1ca40 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1ca50 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e  on are.** not. ^
1ca60 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1ca70 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1ca80 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41  cepted by INSTEA
1ca90 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a  D OF triggers .*
1caa0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
1cab0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 74 68  d..**.** This th
1cac0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1cad0 5f 63 68 61 6e 67 65 73 28 44 29 5d 20 69 6e 74  _changes(D)] int
1cae0 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1caf0 72 74 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  rts the number.*
1cb00 2a 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20 63  * of rows that c
1cb10 68 61 6e 67 65 64 20 64 75 65 20 74 6f 20 53 51  hanged due to SQ
1cb20 4c 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20  L statement run 
1cb30 61 67 61 69 6e 73 74 20 64 61 74 61 62 61 73 65  against database
1cb40 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  .** connection D
1cb50 2e 20 20 41 6e 79 20 63 68 61 6e 67 65 73 20 62  .  Any changes b
1cb60 79 20 6f 74 68 65 72 20 64 61 74 61 62 61 73 65  y other database
1cb70 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 72 65   connections are
1cb80 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 54 6f 20   ignored..** To 
1cb90 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 61  detect changes a
1cba0 67 61 69 6e 73 74 20 61 20 64 61 74 61 62 61 73  gainst a databas
1cbb0 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f 74 68 65  e file from othe
1cbc0 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
1cbd0 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65 20 74 68  nnections use th
1cbe0 65 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76  e [PRAGMA data_v
1cbf0 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20  ersion] command 
1cc00 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  or the.** [SQLIT
1cc10 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52  E_FCNTL_DATA_VER
1cc20 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74  SION] [file cont
1cc30 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rol]..** .** If 
1cc40 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1cc50 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1cc60 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1cc70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1cc80 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1cc90 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1cca0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1ccb0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1ccc0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1ccd0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1cce0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a  t meaningful..**
1ccf0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a  .** See also:.**
1cd00 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68   <ul>.** <li> th
1cd10 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1cd20 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  es()] interface.
1cd30 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f 75  ** <li> the [cou
1cd40 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1cd50 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  a].** <li> the [
1cd60 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1cd70 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e 20  nction].** <li> 
1cd80 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69 6f  the [data_versio
1cd90 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69  n pragma].** <li
1cda0 3e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  > the [SQLITE_FC
1cdb0 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e  NTL_DATA_VERSION
1cdc0 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 5d  ] [file control]
1cdd0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
1cde0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1cdf0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1ce00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ce10 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
1ce20 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
1ce30 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  y.** METHOD: sql
1ce40 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1ce50 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
1ce60 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
1ce70 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
1ce80 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
1ce90 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
1cea0 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
1ceb0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
1cec0 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
1ced0 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
1cee0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
1cef0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
1cf00 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
1cf10 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
1cf20 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
1cf30 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
1cf40 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
1cf50 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
1cf60 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
1cf70 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1cf80 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
1cf90 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
1cfa0 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
1cfb0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
1cfc0 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
1cfd0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1cfe0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
1cff0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
1d000 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1d010 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
1d020 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
1d030 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
1d040 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
1d050 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
1d060 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
1d070 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
1d080 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1d090 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
1d0a0 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
1d0b0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
1d0c0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
1d0d0 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
1d0e0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
1d0f0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
1d100 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
1d110 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
1d120 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
1d130 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
1d140 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
1d150 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
1d160 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1d170 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
1d180 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
1d190 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
1d1a0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
1d1b0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1d1c0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
1d1d0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
1d1e0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
1d1f0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
1d200 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
1d210 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
1d220 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
1d230 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1d240 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1d250 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
1d260 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
1d270 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1d280 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1d290 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
1d2a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
1d2b0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
1d2c0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1d2d0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1d2e0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1d2f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1d300 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
1d310 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
1d320 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
1d330 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
1d340 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
1d350 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
1d360 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
1d370 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
1d380 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
1d390 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
1d3a0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1d3b0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1d3c0 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
1d3d0 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
1d3e0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
1d3f0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
1d400 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1d410 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
1d420 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
1d430 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
1d440 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
1d450 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
1d460 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1d470 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
1d480 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
1d490 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
1d4a0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1d4b0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1d4c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1d4d0 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
1d4e0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
1d4f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
1d500 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1d510 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1d520 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1d530 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
1d540 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
1d550 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
1d560 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
1d570 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
1d580 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
1d590 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
1d5a0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
1d5b0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
1d5c0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1d5d0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
1d5e0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
1d5f0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
1d600 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
1d610 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
1d620 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
1d630 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1d640 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
1d650 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
1d660 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
1d670 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1d680 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
1d690 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
1d6a0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
1d6b0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
1d6c0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
1d6d0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
1d6e0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
1d6f0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
1d700 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
1d710 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
1d720 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
1d730 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
1d740 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
1d750 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
1d760 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
1d770 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
1d780 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
1d790 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
1d7a0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
1d7b0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
1d7c0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
1d7d0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
1d7e0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
1d7f0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
1d800 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
1d810 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
1d820 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
1d830 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
1d840 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
1d850 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1d860 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
1d870 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
1d880 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
1d890 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d8a0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
1d8b0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
1d8c0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
1d8d0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
1d8e0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
1d8f0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
1d900 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
1d910 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
1d920 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
1d930 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
1d940 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
1d950 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
1d960 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
1d970 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
1d980 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
1d990 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1d9a0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
1d9b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
1d9c0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
1d9d0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
1d9e0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1d9f0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
1da00 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1da10 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1da20 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1da30 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1da40 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1da50 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1da60 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1da70 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1da80 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1da90 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1daa0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1dab0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1dac0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1dad0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1dae0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1daf0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1db00 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1db10 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1db20 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1db30 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1db40 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1db50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1db60 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
1db70 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
1db80 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1db90 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
1dba0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1dbb0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
1dbc0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
1dbd0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
1dbe0 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  rrors.** KEYWORD
1dbf0 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72  S: {busy-handler
1dc00 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79   callback} {busy
1dc10 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54   handler}.** MET
1dc20 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1dc30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1dc40 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
1dc50 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
1dc60 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1dc70 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
1dc80 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1dc90 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
1dca0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1dcb0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1dcc0 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
1dcd0 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
1dce0 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
1dcf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1dd00 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
1dd10 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
1dd20 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
1dd30 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
1dd40 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1dd50 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
1dd60 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
1dd70 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
1dd80 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1dd90 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
1dda0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
1ddb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
1ddc0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1ddd0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
1dde0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
1ddf0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1de00 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
1de10 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
1de20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1de30 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
1de40 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1de50 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
1de60 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
1de70 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
1de80 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1de90 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
1dea0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
1deb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
1dec0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
1ded0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
1dee0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1def0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1df00 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
1df10 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1df20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1df30 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1df40 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
1df50 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
1df60 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
1df70 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76  een invoked prev
1df80 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73  iously for the s
1df90 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
1dfa0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1dfb0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1dfc0 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1dfd0 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1dfe0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1dff0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1e000 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1e010 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75  TE_BUSY] is retu
1e020 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61  rned.** to the a
1e030 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  pplication..** ^
1e040 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1e050 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1e060 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1e070 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1e080 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  e to access the 
1e090 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
1e0a0 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
1e0b0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
1e0c0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
1e0d0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
1e0e0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
1e0f0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
1e100 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
1e110 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
1e120 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
1e130 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
1e140 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
1e150 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
1e160 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
1e170 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
1e180 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
1e190 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1e1a0 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1e1b0 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66  ation instead of
1e1c0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a   invoking the .*
1e1d0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
1e1e0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1e1f0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1e200 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1e210 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1e220 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1e230 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1e240 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1e250 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1e260 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1e270 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1e280 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1e290 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1e2a0 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1e2b0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1e2c0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1e2d0 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1e2e0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1e2f0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1e300 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1e310 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1e320 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1e330 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1e340 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1e350 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1e360 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1e370 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1e380 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1e390 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1e3a0 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1e3b0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1e3c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1e3d0 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1e3e0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1e3f0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1e400 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1e410 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1e420 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1e430 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1e440 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1e450 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1e460 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1e470 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1e480 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  NULL..**.** ^(Th
1e490 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1e4a0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1e4b0 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
1e4c0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
1e4d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1e4e0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
1e4f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
1e500 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
1e510 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
1e520 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
1e530 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1e540 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1e550 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69  ].** or evaluati
1e560 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  ng [PRAGMA busy_
1e570 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20  timeout=N] will 
1e580 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75  change the.** bu
1e590 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74  sy handler and t
1e5a0 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72  hus clear any pr
1e5b0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73  eviously set bus
1e5c0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1e5d0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1e5e0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1e5f0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1e600 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1e610 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1e620 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1e630 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1e640 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  dler.  In other 
1e650 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75  words,.** the bu
1e660 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f  sy handler is no
1e670 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e  t reentrant.  An
1e680 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1e690 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1e6a0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1e6b0 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1e6c0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1e6d0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1e6e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1e6f0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1e700 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1e710 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1e720 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
1e730 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1e740 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28  er(sqlite3*,int(
1e750 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f  *)(void*,int),vo
1e760 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1e770 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1e780 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1e790 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1e7a0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1e7b0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1e7c0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1e7d0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1e7e0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1e7f0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1e800 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1e810 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1e820 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1e830 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1e840 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1e850 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1e860 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1e870 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1e880 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1e890 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1e8a0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1e8b0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1e8c0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1e8d0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1e8e0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1e8f0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1e900 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1e910 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1e920 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1e930 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1e940 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1e950 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1e960 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1e970 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1e980 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1e990 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1e9a0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1e9b0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1e9c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e9d0 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1e9e0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1e9f0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1ea00 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1ea10 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1ea20 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1ea30 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1ea40 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1ea50 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1ea60 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1ea70 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1ea80 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1ea90 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1eaa0 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ut].*/.int sqlit
1eab0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1eac0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1ead0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1eae0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1eaf0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1eb00 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1eb10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1eb20 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1eb30 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1eb40 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1eb50 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1eb60 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1eb70 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1eb80 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1eb90 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1eba0 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1ebb0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1ebc0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1ebd0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1ebe0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1ebf0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1ec00 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1ec10 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1ec20 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1ec30 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1ec40 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1ec50 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1ec60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1ec70 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1ec80 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1ec90 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1eca0 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1ecb0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1ecc0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1ecd0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1ece0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1ecf0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1ed00 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1ed10 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1ed20 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1ed30 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1ed40 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1ed50 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1ed60 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1ed70 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1ed80 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1ed90 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1eda0 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1edb0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1edc0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1edd0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1ede0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1edf0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1ee00 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1ee10 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1ee20 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1ee30 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1ee40 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1ee50 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1ee60 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1ee70 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1ee80 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1ee90 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1eea0 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1eeb0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1eec0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1eed0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1eee0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1eef0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1ef00 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1ef10 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1ef20 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1ef30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1ef40 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1ef50 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1ef60 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1ef70 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1ef80 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1ef90 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1efa0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1efb0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1efc0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1efd0 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1efe0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1eff0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1f000 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1f010 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1f020 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1f030 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1f040 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1f050 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1f060 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1f070 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1f080 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1f090 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1f0a0 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1f0b0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1f0c0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1f0d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1f0e0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1f0f0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1f100 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1f110 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1f120 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1f130 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1f140 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1f150 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1f160 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1f170 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1f180 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1f190 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1f1a0 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1f1b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1f1c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1f1d0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1f1e0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1f1f0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1f200 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1f210 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1f220 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1f230 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1f240 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1f250 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1f260 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1f270 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1f280 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1f290 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1f2a0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1f2b0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1f2c0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1f2d0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1f2e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1f2f0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1f300 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1f310 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1f320 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1f330 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1f340 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1f350 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1f360 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1f370 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1f380 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1f390 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1f3a0 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1f3b0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1f3c0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1f3d0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1f3e0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1f3f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1f400 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1f410 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1f420 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1f430 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1f440 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1f450 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1f460 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1f470 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1f480 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1f490 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1f4a0 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1f4b0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1f4c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1f4d0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1f4e0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1f4f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1f500 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1f510 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1f520 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1f530 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1f540 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1f550 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1f560 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1f570 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1f580 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1f590 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1f5a0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1f5b0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1f5c0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1f5d0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1f5e0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1f5f0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1f600 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1f610 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1f620 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1f630 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1f640 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1f650 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1f660 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1f670 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1f680 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1f690 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1f6a0 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1f6b0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1f6c0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1f6d0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1f6e0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1f6f0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1f700 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1f710 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1f720 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1f730 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1f740 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1f750 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1f760 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1f770 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1f780 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1f790 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1f7a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1f7b0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1f7c0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1f7d0 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1f7e0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1f7f0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1f800 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1f810 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1f820 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1f830 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1f840 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1f850 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1f860 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1f870 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1f880 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1f890 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1f8a0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1f8b0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1f8c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1f8d0 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1f8e0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1f8f0 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1f900 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1f910 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1f920 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1f930 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1f940 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1f950 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1f960 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1f970 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1f980 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
1f990 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
1f9a0 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
1f9b0 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d 61 74 74  e common formatt
1f9c0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d  ing options from
1f9d0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1f9e0 20 6c 69 62 72 61 72 79 20 70 72 69 6e 74 66 28   library printf(
1f9f0 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20  ) .** plus some 
1fa00 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73  additional non-s
1fa10 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 20  tandard formats 
1fa20 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20 5b 25 77  ([%q], [%Q], [%w
1fa30 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e 0a 2a 2a  ], and [%z])..**
1fa40 20 53 65 65 20 74 68 65 20 5b 62 75 69 6c 74 2d   See the [built-
1fa50 69 6e 20 70 72 69 6e 74 66 28 29 5d 20 64 6f 63  in printf()] doc
1fa60 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 64  umentation for d
1fa70 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  etails..**.** ^T
1fa80 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1fa90 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1faa0 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1fab0 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1fac0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1fad0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1fae0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1faf0 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a 2a 20 54  alloc64()]..** T
1fb00 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1fb10 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1fb20 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1fb30 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1fb40 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1fb50 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1fb60 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1fb70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1fb80 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1fb90 36 34 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  64()] is unable 
1fba0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1fbb0 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1fbc0 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1fbd0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1fbe0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1fbf0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1fc00 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1fc10 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1fc20 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1fc30 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1fc40 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1fc50 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1fc60 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1fc70 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1fc80 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1fc90 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1fca0 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1fcb0 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1fcc0 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1fcd0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1fce0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1fcf0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1fd00 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1fd10 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1fd20 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1fd30 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1fd40 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1fd50 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1fd60 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1fd70 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1fd80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1fd90 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1fda0 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1fdb0 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1fdc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1fdd0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1fde0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1fdf0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1fe00 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1fe10 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1fe20 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1fe30 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1fe40 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1fe50 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1fe60 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1fe70 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1fe80 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1fe90 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1fea0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1feb0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1fec0 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1fed0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1fee0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1fef0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1ff00 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1ff10 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1ff20 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1ff30 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1ff40 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1ff50 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1ff60 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1ff70 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1ff80 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1ff90 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1ffa0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1ffb0 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1ffc0 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1ffd0 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1ffe0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1fff0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
20000 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
20010 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
20020 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
20030 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
20040 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
20050 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
20060 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69  :  [built-in pri
20070 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e 74 66 28  ntf()], [printf(
20080 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 0a  ) SQL function].
20090 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
200a0 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
200b0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
200c0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
200d0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
200e0 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
200f0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
20100 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
20110 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
20120 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
20130 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
20140 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
20150 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
20160 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
20170 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
20180 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
20190 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
201a0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
201b0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
201c0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
201d0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
201e0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
201f0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
20200 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
20210 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
20220 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
20230 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
20240 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
20250 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
20260 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
20270 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
20280 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
20290 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
202a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
202b0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
202c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
202d0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
202e0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
202f0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
20300 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
20310 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
20320 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20330 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
20340 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
20350 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
20360 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
20370 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
20380 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
20390 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
203a0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
203b0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
203c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
203d0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
203e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
203f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20400 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
20410 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
20420 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
20430 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
20440 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
20450 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
20460 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
20470 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
20480 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
20490 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
204a0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
204b0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
204c0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
204d0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
204e0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
204f0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
20500 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
20510 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
20520 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
20530 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
20540 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
20550 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
20560 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
20570 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
20580 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
20590 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
205a0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
205b0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
205c0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
205d0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
205e0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
205f0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
20600 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
20610 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
20620 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
20630 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
20640 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
20650 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
20660 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
20670 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
20680 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
20690 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
206a0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
206b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
206c0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
206d0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
206e0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
206f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
20700 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
20710 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
20720 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
20730 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20740 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
20750 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
20760 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
20770 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
20780 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
20790 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
207a0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
207b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
207c0 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
207d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
207e0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
207f0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
20800 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
20810 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
20820 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
20830 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
20840 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
20850 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
20860 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
20870 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
20880 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
20890 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
208a0 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
208b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
208c0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
208d0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
208e0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
208f0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
20900 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
20910 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
20920 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
20930 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
20940 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
20950 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20960 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
20970 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
20980 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20990 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
209a0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
209b0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
209c0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
209d0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
209e0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
209f0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
20a00 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
20a10 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
20a20 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
20a30 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
20a40 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
20a50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
20a60 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
20a70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
20a80 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
20a90 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
20aa0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
20ab0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
20ac0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
20ad0 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
20ae0 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
20af0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
20b00 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
20b10 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
20b20 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
20b30 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
20b40 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
20b50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
20b60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
20b70 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
20b80 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
20b90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
20ba0 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
20bb0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
20bc0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
20bd0 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
20be0 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
20bf0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
20c00 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
20c10 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
20c20 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
20c30 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
20c40 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
20c50 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
20c60 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
20c70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
20c80 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
20c90 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
20ca0 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
20cb0 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
20cc0 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
20cd0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
20ce0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
20cf0 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
20d00 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
20d10 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
20d20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
20d30 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
20d40 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
20d50 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
20d60 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
20d70 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
20d80 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
20d90 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
20da0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
20db0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20dc0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
20dd0 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
20de0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
20df0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20e00 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
20e10 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
20e20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
20e30 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
20e40 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
20e50 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
20e60 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
20e70 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
20e80 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
20e90 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
20ea0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
20eb0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
20ec0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
20ed0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
20ee0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
20ef0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
20f00 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
20f10 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
20f20 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
20f30 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
20f40 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
20f50 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
20f60 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
20f70 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
20f80 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
20f90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
20fa0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
20fb0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
20fc0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
20fd0 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
20fe0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
20ff0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
21000 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
21010 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
21020 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
21030 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
21040 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
21050 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
21060 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
21070 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
21080 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
21090 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
210a0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
210b0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
210c0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
210d0 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
210e0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
210f0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
21100 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
21110 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
21120 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
21130 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
21140 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
21150 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
21160 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
21170 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
21180 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
21190 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
211a0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
211b0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
211c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
211d0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
211e0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
211f0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
21200 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
21210 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
21220 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
21230 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
21240 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
21250 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
21260 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
21270 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
21280 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
21290 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
212a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
212b0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
212c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
212d0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
212e0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
212f0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
21300 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
21310 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  64);.void *sqlit
21320 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
21330 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  , int);.void *sq
21340 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
21350 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
21360 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
21370 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
21380 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  ;.sqlite3_uint64
21390 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
213a0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
213b0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
213c0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
213d0 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
213e0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
213f0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
21400 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
21410 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
21420 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
21430 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
21440 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
21450 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
21460 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
21470 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
21480 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
21490 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
214a0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
214b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
214c0 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
214d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
214e0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
214f0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
21500 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
21510 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
21520 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
21530 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
21540 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
21550 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
21560 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
21570 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
21580 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
21590 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
215a0 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
215b0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
215c0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
215d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
215e0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
215f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
21600 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
21610 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
21620 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
21630 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
21640 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
21650 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
21660 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
21670 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
21680 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
21690 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
216a0 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
216b0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
216c0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
216d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
216e0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
216f0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
21700 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
21710 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
21720 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
21730 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
21740 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
21750 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
21760 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
21770 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
21780 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
21790 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
217a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
217b0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
217c0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
217d0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
217e0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
217f0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
21800 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
21810 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
21820 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
21830 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
21840 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21850 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
21860 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
21870 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
21880 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
21890 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
218a0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
218b0 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
218c0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
218d0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
218e0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
218f0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
21900 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
21910 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
21920 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
21930 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
21940 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
21950 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
21960 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
21970 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
21980 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
21990 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
219a0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
219b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
219c0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
219d0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
219e0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
219f0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
21a00 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
21a10 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
21a20 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
21a30 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
21a40 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
21a50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
21a60 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
21a70 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
21a80 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
21a90 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
21aa0 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
21ab0 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
21ac0 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
21ad0 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
21ae0 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
21af0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
21b00 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
21b10 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
21b20 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
21b30 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
21b40 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
21b50 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
21b60 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
21b70 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
21b80 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
21b90 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
21ba0 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
21bb0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
21bc0 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
21bd0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
21be0 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
21bf0 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
21c00 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
21c10 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
21c20 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
21c30 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
21c40 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
21c50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
21c60 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
21c70 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
21c80 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
21c90 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ite3.** KEYWORDS
21ca0 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63 61  : {authorizer ca
21cb0 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54  llback}.**.** ^T
21cc0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
21cd0 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
21ce0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
21cf0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
21d00 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
21d10 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
21d20 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
21d30 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
21d40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21d50 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
21d60 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
21d70 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
21d80 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
21d90 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
21da0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
21db0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21dc0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
21dd0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
21de0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
21df0 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  re16()], [sqlite
21e00 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21e10 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  ],.** and [sqlit
21e20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
21e30 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
21e40 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
21e50 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
21e60 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
21e70 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
21e80 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
21e90 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
21ea0 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
21eb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
21ec0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
21ed0 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
21ee0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
21ef0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
21f00 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
21f10 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
21f20 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
21f30 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
21f40 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
21f50 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
21f60 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
21f70 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
21f80 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
21f90 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
21fa0 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
21fb0 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
21fc0 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
21fd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
21fe0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
21ff0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
22000 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
22010 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
22020 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
22030 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
22040 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
22050 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
22060 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
22070 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
22080 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
22090 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
220a0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
220b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
220c0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
220d0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
220e0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
220f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
22100 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
22110 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
22120 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
22130 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
22140 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
22150 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
22160 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
22170 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22180 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
22190 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
221a0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
221b0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
221c0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
221d0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
221e0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
221f0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
22200 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
22210 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
22220 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22230 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
22240 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
22250 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
22260 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22270 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
22280 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
22290 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
222a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
222b0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
222c0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
222d0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
222e0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
222f0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
22300 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
22310 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
22320 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
22330 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
22340 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68 65  llback are eithe
22350 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  r NULL pointers 
22360 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  or zero-terminat
22370 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74 68  ed strings.** th
22380 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
22390 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62  ional details ab
223a0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
223b0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
223c0 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
223d0 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65 20   must always be 
223e0 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63 6f  prepared to enco
223f0 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  unter a NULL poi
22400 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f  nter in any.** o
22410 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72 6f  f the third thro
22420 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70 61  ugh the sixth pa
22430 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
22440 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61  authorization ca
22450 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49  llback..**.** ^I
22460 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
22470 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
22480 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
22490 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
224a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
224b0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
224c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
224d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
224e0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
224f0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
22500 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
22510 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
22520 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
22530 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
22540 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
22550 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
22560 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
22570 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
22580 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
22590 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
225a0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
225b0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
225c0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
225d0 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 74  le..** ^When a t
225e0 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e 63  able is referenc
225f0 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54 5d  ed by a [SELECT]
22600 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76   but no column v
22610 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78 74  alues are.** ext
22620 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61 74  racted from that
22630 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61 6d   table (for exam
22640 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20 6c  ple in a query l
22650 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20 63  ike.** "SELECT c
22660 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61 62  ount(*) FROM tab
22670 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51 4c  ") then the [SQL
22680 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f 72  ITE_READ] author
22690 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
226a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
226b0 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65 20   for that table 
226c0 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e 61  with a column na
226d0 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65 6d  me that is an em
226e0 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  pty string..** ^
226f0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
22700 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
22710 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
22720 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
22730 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
22740 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
22750 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
22760 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
22770 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
22780 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
22790 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
227a0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
227b0 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
227c0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
227d0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
227e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
227f0 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
22800 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
22810 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
22820 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
22830 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
22840 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
22850 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
22860 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
22870 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
22880 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
22890 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
228a0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
228b0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
228c0 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
228d0 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
228e0 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
228f0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
22900 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
22910 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
22920 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
22930 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
22940 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
22950 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
22960 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
22970 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
22980 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
22990 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
229a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
229b0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
229c0 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
229d0 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
229e0 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
229f0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
22a00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
22a10 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
22a20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
22a30 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
22a40 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
22a50 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
22a60 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
22a70 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
22a80 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
22a90 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
22aa0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
22ab0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
22ac0 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
22ad0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
22ae0 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
22af0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
22b00 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
22b10 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
22b20 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
22b30 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
22b40 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
22b50 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
22b60 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
22b70 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
22b80 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
22b90 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
22ba0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
22bb0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
22bc0 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
22bd0 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
22be0 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
22bf0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
22c00 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
22c10 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
22c20 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
22c30 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
22c40 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
22c50 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
22c60 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
22c70 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
22c80 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
22c90 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
22ca0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
22cb0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
22cc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22cd0 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
22ce0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22cf0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
22d00 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
22d10 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
22d20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22d30 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
22d40 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
22d50 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
22d60 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
22d70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22d80 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
22d90 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
22da0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
22db0 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
22dc0 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
22dd0 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
22de0 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
22df0 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
22e00 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
22e10 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
22e20 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
22e30 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
22e40 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22e50 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
22e60 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
22e70 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
22e80 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
22e90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22ea0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22eb0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
22ec0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22ed0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
22ee0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
22ef0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
22f00 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
22f10 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
22f20 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
22f30 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
22f40 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
22f50 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
22f60 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
22f70 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
22f80 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
22f90 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
22fa0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
22fb0 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
22fc0 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
22fd0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22fe0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
22ff0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
23000 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
23010 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
23020 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
23030 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
23040 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
23050 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23060 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
23070 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
23080 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
23090 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
230a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
230b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
230c0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
230d0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
230e0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
230f0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
23100 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
23110 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
23120 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
23130 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
23140 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
23150 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
23160 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
23170 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
23180 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
23190 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
231a0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
231b0 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
231c0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
231d0 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
231e0 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
231f0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
23200 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
23210 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
23220 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
23230 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
23240 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
23250 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
23260 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
23270 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23280 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
23290 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
232a0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
232b0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
232c0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
232d0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
232e0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
232f0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
23300 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
23310 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
23320 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
23330 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
23340 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
23350 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
23360 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
23370 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
23380 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
23390 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
233a0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
233b0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
233c0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
233d0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
233e0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
233f0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
23400 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
23410 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
23420 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
23430 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
23440 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
23450 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
23460 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
23470 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
23480 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
23490 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
234a0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
234b0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
234c0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
234d0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
234e0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
234f0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
23500 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
23510 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
23520 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
23530 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
23540 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
23550 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
23560 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
23570 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
23580 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
23590 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
235a0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
235b0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
235c0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
235d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
235e0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
235f0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
23600 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
23610 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
23620 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
23630 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
23640 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
23650 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
23660 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
23670 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
23680 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
23690 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
236a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
236b0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
236c0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
236d0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
236e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
236f0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
23700 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
23710 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23720 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23730 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
23740 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
23750 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23760 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23770 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23780 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
23790 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
237a0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
237b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
237c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
237d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
237e0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
237f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23800 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23810 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23820 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
23830 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
23840 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
23850 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23860 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23870 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
23880 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
23890 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
238a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
238b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
238c0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
238d0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
238e0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
238f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
23900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23910 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
23920 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
23930 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
23940 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23950 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23960 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
23970 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
23980 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
23990 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
239a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
239b0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
239c0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
239d0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
239e0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
239f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23a00 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
23a10 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
23a20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23a30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23a50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
23a60 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
23a70 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
23a80 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23a90 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23aa0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
23ab0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
23ac0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
23ad0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23ae0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
23af0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
23b00 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
23b10 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
23b20 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
23b30 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
23b40 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
23b50 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
23b60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23b70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23b80 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
23b90 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
23ba0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
23bb0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
23bc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23bd0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
23be0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
23bf0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
23c00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
23c10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23c20 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
23c30 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
23c40 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23c50 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23c60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23c70 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
23c80 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
23c90 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
23ca0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
23cb0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
23cc0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
23cd0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
23ce0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23cf0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
23d00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23d10 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
23d20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
23d30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23d40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23d50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23d60 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
23d70 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
23d80 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
23d90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23da0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23db0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
23dc0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
23dd0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
23de0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
23df0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23e00 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
23e10 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
23e20 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
23e30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23e40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23e50 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
23e60 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
23e70 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
23e80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
23ea0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
23eb0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
23ec0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
23ed0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
23ee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
23ef0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
23f00 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
23f10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23f20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
23f40 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
23f50 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
23f60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
23f70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23f80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
23f90 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
23fa0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
23fb0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
23fc0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
23fd0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
23fe0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
23ff0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
24000 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
24010 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
24020 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
24030 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
24040 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
24050 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
24060 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
24070 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
24080 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
24090 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
240a0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
240b0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
240c0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
240d0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
240e0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
240f0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
24100 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
24110 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
24120 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
24130 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24140 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
24150 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
24160 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
24170 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
24180 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
24190 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
241a0 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73  e deprecated. Us
241b0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
241c0 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  race_v2()] inter
241d0 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20  face.** instead 
241e0 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20  of the routines 
241f0 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a  described here..
24200 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24210 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
24220 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
24230 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
24240 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
24250 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
24260 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
24270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
24280 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
24290 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
242a0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
242b0 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
242c0 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
242d0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
242e0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
242f0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
24300 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24310 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
24320 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
24330 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
24340 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
24350 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
24360 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
24370 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
24380 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
24390 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
243a0 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
243b0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
243c0 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
243d0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
243e0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
243f0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
24400 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
24410 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
24420 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
24430 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
24440 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
24450 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
24460 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
24470 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
24480 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
24490 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
244a0 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
244b0 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
244c0 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
244d0 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
244e0 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
244f0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
24500 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
24510 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
24520 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
24530 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
24540 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
24550 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
24560 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
24570 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
24580 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
24590 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
245a0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
245b0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
245c0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
245d0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
245e0 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
245f0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
24600 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
24610 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
24620 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
24630 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
24640 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
24650 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
24660 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
24670 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
24680 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
24690 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
246a0 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
246b0 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
246c0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
246d0 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
246e0 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
246f0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
24700 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
24710 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
24720 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
24730 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
24740 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
24750 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
24760 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
24770 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
24780 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
24790 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
247a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
247b0 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ace(sqlite3*,.  
247c0 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
247d0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
247e0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
247f0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
24800 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
24810 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
24820 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
24830 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
24840 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
24850 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
24860 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
24870 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65  Trace Event Code
24880 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
24890 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a  QLITE_TRACE.**.*
248a0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
248b0 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73  s identify class
248c0 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61  es of events tha
248d0 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72  t can be monitor
248e0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ed.** using the 
248f0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
24900 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67  2()] tracing log
24910 69 63 2e 20 20 54 68 65 20 4d 20 61 72 67 75 6d  ic.  The M argum
24920 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
24930 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c  e3_trace_v2(D,M,
24940 58 2c 50 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65  X,P)] is an OR-e
24950 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
24960 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a   one or more of.
24970 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
24980 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68   constants.  ^Th
24990 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
249a0 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
249b0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65  llback.** is one
249c0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
249d0 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  g constants..**.
249e0 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63  ** New tracing c
249f0 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
24a00 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
24a10 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
24a20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
24a30 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d  k has four argum
24a40 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28  ents: xCallback(
24a50 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
24a60 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
24a70 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67  one of the integ
24a80 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62  er type codes ab
24a90 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ove..** ^The C a
24aa0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
24ab0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
24ac0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
24ad0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  in as the.** fou
24ae0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
24af0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
24b00 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61  2()]..** The P a
24b10 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
24b20 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
24b30 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
24b40 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64  d on T..**.** <d
24b50 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  l>.** [[SQLITE_T
24b60 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e  RACE_STMT]] <dt>
24b70 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
24b80 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  T</dt>.** <dd>^A
24b90 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  n SQLITE_TRACE_S
24ba0 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  TMT callback is 
24bb0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70  invoked when a p
24bc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24bd0 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e  t.** first begin
24be0 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f  s running and po
24bf0 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20  ssibly at other 
24c00 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65  times during the
24c10 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  .** execution of
24c20 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
24c30 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73  atement, such as
24c40 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
24c50 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72   each.** trigger
24c60 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68   subprogram. ^Th
24c70 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
24c80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
24c90 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
24ca0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58  atement]. ^The X
24cb0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
24cc0 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
24cd0 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  ng which.** is t
24ce0 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51  he unexpanded SQ
24cf0 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72  L text of the pr
24d00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24d10 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
24d20 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  nt .** that indi
24d30 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61  cates the invoca
24d40 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65  tion of a trigge
24d50 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  r.  ^The callbac
24d60 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a  k can compute.**
24d70 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74   the same text t
24d80 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62  hat would have b
24d90 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  een returned by 
24da0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
24db0 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20  te3_trace()].** 
24dc0 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69  interface by usi
24dd0 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ng the X argumen
24de0 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20  t when X begins 
24df0 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e  with "--" and in
24e00 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  voking.** [sqlit
24e10 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
24e20 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  P)] otherwise..*
24e30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
24e40 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64  ACE_PROFILE]] <d
24e50 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  t>SQLITE_TRACE_P
24e60 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ROFILE</dt>.** <
24e70 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
24e80 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
24e90 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70  back provides ap
24ea0 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20  proximately the 
24eb0 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  same.** informat
24ec0 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64  ion as is provid
24ed0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
24ee0 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61  e3_profile()] ca
24ef0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
24f00 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
24f10 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
24f20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24f30 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
24f40 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
24f50 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74   to a 64-bit int
24f60 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
24f70 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a  e estimated of.*
24f80 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
24f90 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20  nanosecond that 
24fa0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
24fb0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
24fc0 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  un..** ^The SQLI
24fd0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
24fe0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24ff0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74  oked when the st
25000 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
25010 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
25020 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74  _TRACE_ROW]] <dt
25030 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  >SQLITE_TRACE_RO
25040 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  W</dt>.** <dd>^A
25050 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  n SQLITE_TRACE_R
25060 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  OW callback is i
25070 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
25080 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
25090 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
250a0 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  s a single row o
250b0 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e  f result.  .** ^
250c0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
250d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
250e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
250f0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
25100 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  ** X argument is
25110 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   unused..**.** [
25120 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  [SQLITE_TRACE_CL
25130 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  OSE]] <dt>SQLITE
25140 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74  _TRACE_CLOSE</dt
25150 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
25160 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
25170 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
25180 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62  ked when a datab
25190 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
251a0 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68  n closes..** ^Th
251b0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
251c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
251d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
251e0 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a  ction] object.**
251f0 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d   and the X argum
25200 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
25210 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
25220 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
25230 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a  STMT       0x01.
25240 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
25250 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20  RACE_PROFILE    
25260 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x02.#define SQL
25270 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20  ITE_TRACE_ROW   
25280 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e       0x04.#defin
25290 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  e SQLITE_TRACE_C
252a0 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a  LOSE      0x08..
252b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
252c0 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a  SQL Trace Hook.*
252d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
252e0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
252f0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
25300 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  M,X,P) interface
25310 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61   registers a tra
25320 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ce callback.** f
25330 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73  unction X agains
25340 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  t [database conn
25350 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67  ection] D, using
25360 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d   property mask M
25370 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20  .** and context 
25380 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20  pointer P.  ^If 
25390 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  the X callback i
253a0 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20  s.** NULL or if 
253b0 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65  the M mask is ze
253c0 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67  ro, then tracing
253d0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
253e0 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74  he.** M argument
253f0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62   should be the b
25400 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d  itwise OR-ed com
25410 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a  bination of.** z
25420 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c  ero or more [SQL
25430 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74  ITE_TRACE] const
25440 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  ants..**.** ^Eac
25450 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  h call to either
25460 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
25470 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
25480 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73  e_v2() overrides
25490 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61   .** (cancels) a
254a0 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  ny prior calls t
254b0 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  o sqlite3_trace(
254c0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
254d0 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ce_v2()..**.** ^
254e0 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  The X callback i
254f0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
25500 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76  er any of the ev
25510 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20  ents identified 
25520 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63  by .** mask M oc
25530 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67  cur.  ^The integ
25540 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  er return value 
25550 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63  from the callbac
25560 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  k is currently.*
25570 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67  * ignored, thoug
25580 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67  h this may chang
25590 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
255a0 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a  ases.  Callback.
255b0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
255c0 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ns should return
255d0 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20   zero to ensure 
255e0 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69  future compatibi
255f0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  lity..**.** ^A t
25600 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
25610 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f   invoked with fo
25620 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61  ur arguments: ca
25630 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
25640 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
25650 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
25660 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
25670 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f  .** constants to
25680 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68   indicate why th
25690 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69  e callback was i
256a0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
256b0 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
256c0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
256d0 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ext pointer..** 
256e0 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
256f0 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
25700 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
25710 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
25720 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
25730 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65  _trace_v2() inte
25740 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
25750 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65  d to replace the
25760 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
25770 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74  faces [sqlite3_t
25780 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  race()] and [sql
25790 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c  ite3_profile()],
257a0 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a   both of which.*
257b0 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  * are deprecated
257c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
257d0 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c  _trace_v2(.  sql
257e0 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65  ite3*,.  unsigne
257f0 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a  d uMask,.  int(*
25800 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67  xCallback)(unsig
25810 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c  ned,void*,void*,
25820 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  void*),.  void *
25830 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pCtx.);../*.** C
25840 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
25850 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
25860 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
25870 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
25880 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
25890 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
258a0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
258b0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
258c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
258d0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
258e0 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
258f0 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
25900 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
25910 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
25920 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
25930 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
25940 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
25950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25960 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
25970 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
25980 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
25990 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
259a0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
259b0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
259c0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
259d0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
259e0 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
259f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
25a00 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
25a10 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
25a20 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
25a30 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
25a40 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
25a50 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
25a60 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
25a70 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
25a80 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
25a90 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
25aa0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
25ab0 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
25ac0 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
25ad0 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
25ae0 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
25af0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
25b00 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
25b10 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
25b20 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
25b30 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
25b40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25b50 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
25b60 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
25b70 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
25b80 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
25b90 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
25ba0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
25bb0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
25bc0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
25bd0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
25be0 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
25bf0 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
25c00 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
25c10 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
25c20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
25c30 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
25c40 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
25c50 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
25c60 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
25c70 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
25c80 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
25c90 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
25ca0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
25cb0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
25cc0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
25cd0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
25ce0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
25cf0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
25d00 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
25d10 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
25d20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
25d30 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
25d40 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
25d50 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
25d60 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25d70 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
25d80 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
25d90 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
25da0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
25db0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
25dc0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
25dd0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
25de0 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
25df0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
25e00 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
25e10 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
25e20 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
25e30 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
25e40 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
25e50 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
25e60 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
25e70 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
25e80 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
25e90 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
25ea0 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
25eb0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
25ec0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
25ed0 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
25ee0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
25ef0 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
25f00 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
25f10 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
25f20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
25f30 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
25f40 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
25f50 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
25f60 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
25f70 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
25f80 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
25f90 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
25fa0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
25fb0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
25fc0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
25fd0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
25fe0 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
25ff0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
26000 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
26010 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
26020 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
26030 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
26040 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
26050 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
26060 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
26070 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
26080 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
26090 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
260a0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
260b0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
260c0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
260d0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
260e0 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
260f0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
26100 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
26110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
26120 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
26130 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
26140 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
26150 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
26160 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
26170 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
26180 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
26190 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
261a0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
261b0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
261c0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
261d0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
261e0 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
261f0 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
26200 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
26210 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
26220 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
26230 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
26240 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
26250 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
26260 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
26270 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
26280 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
26290 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
262a0 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
262b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
262c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
262d0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
262e0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
262f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
26300 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
26310 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
26320 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
26330 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
26340 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
26350 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
26360 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
26370 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
26380 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26390 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
263a0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
263b0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
263c0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
263d0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
263e0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
263f0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
26400 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
26410 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
26420 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
26430 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
26440 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
26450 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
26460 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
26470 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
26480 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
26490 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
264a0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
264b0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
264c0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
264d0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
264e0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
264f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
26500 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
26510 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
26520 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
26530 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
26540 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
26550 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
26560 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
26570 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
26580 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
26590 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
265a0 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
265b0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
265c0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
265d0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
265e0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
265f0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
26600 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26610 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
26620 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
26630 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
26640 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
26650 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
26660 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
26670 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
26680 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
26690 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
266a0 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
266b0 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
266c0 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
266d0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
266e0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
266f0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
26700 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
26710 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
26720 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
26730 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
26740 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
26750 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
26760 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
26770 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
26780 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
26790 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
267a0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
267b0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
267c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
267d0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
267e0 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
267f0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
26800 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
26810 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
26820 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
26830 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
26840 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
26850 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
26860 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
26870 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
26880 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
26890 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
268a0 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
268b0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
268c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
268d0 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
268e0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
268f0 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
26900 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
26910 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
26920 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
26930 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
26940 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
26950 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
26960 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
26970 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
26980 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
26990 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
269a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
269b0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
269c0 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
269d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
269e0 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
269f0 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
26a00 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
26a10 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
26a20 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
26a30 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
26a40 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
26a50 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
26a60 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
26a70 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
26a80 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
26a90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
26aa0 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
26ab0 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
26ac0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
26ad0 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
26ae0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
26af0 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
26b00 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
26b10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
26b20 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
26b30 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
26b40 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
26b50 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
26b60 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
26b70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
26b80 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
26b90 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
26ba0 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
26bb0 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
26bc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
26bd0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
26be0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26bf0 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
26c00 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
26c10 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
26c20 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
26c30 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
26c40 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
26c50 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
26c60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
26c70 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
26c80 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
26c90 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
26ca0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
26cb0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
26cc0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
26cd0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
26ce0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
26cf0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
26d00 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
26d10 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
26d20 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
26d30 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
26d40 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
26d50 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
26d60 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
26d70 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
26d80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26d90 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
26da0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
26db0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
26dc0 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
26dd0 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
26de0 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
26df0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
26e00 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
26e10 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
26e20 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
26e30 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26e40 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
26e50 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
26e60 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
26e70 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
26e80 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
26e90 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
26ea0 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
26eb0 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
26ec0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
26ed0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
26ee0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
26ef0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
26f00 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
26f10 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
26f20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
26f30 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
26f40 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
26f50 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
26f60 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
26f70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26f80 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
26f90 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
26fa0 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
26fb0 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
26fc0 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
26fd0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
26fe0 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
26ff0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
27000 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
27010 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
27020 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
27030 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
27040 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
27050 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
27060 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
27070 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
27080 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
27090 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
270a0 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
270b0 20 73 65 74 20 69 6e 20 74 68 65 20 74 68 69 72   set in the thir
270c0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
270d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
270e0 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
270f0 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
27100 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
27110 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
27120 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
27130 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
27140 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
27150 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
27160 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
27170 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
27180 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  ..** URI filenam
27190 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
271a0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
271b0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
271c0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
271d0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
271e0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
271f0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
27200 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
27210 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
27220 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
27230 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
27240 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
27250 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
27260 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
27270 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
27280 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
27290 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
272a0 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
272b0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
272c0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
272d0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
272e0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
272f0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
27300 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
27310 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
27320 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
27330 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
27340 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
27350 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
27360 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
27370 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
27380 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
27390 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
273a0 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
273b0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
273c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
273d0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
273e0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
273f0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
27400 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
27410 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
27420 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
27430 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
27440 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
27450 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
27460 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
27470 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
27480 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
27490 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
274a0 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
274b0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
274c0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
274d0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
274e0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
274f0 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
27500 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
27510 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
27520 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
27530 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
27540 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
27550 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
27560 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
27570 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
27580 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
27590 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
275a0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
275b0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
275c0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
275d0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
275e0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
275f0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
27600 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
27610 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
27620 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
27630 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
27640 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
27650 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
27660 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
27670 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
27680 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
27690 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
276a0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
276b0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
276c0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
276d0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
276e0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
276f0 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
27700 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
27710 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
27720 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
27730 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
27740 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
27750 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
27760 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
27770 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
27780 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
27790 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
277a0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
277b0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
277c0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
277d0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
277e0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
277f0 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
27800 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
27810 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
27820 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
27830 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
27840 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
27850 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
27860 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
27870 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
27880 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
27890 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
278a0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
278b0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
278c0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
278d0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
278e0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
278f0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
27900 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
27910 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
27920 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
27930 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
27940 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
27950 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
27960 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
27970 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
27980 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
27990 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
279a0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
279b0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
279c0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
279d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
279e0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
279f0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
27a00 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
27a10 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
27a20 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
27a30 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
27a40 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
27a50 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
27a60 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
27a70 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
27a80 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
27a90 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
27aa0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
27ab0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
27ac0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
27ad0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
27ae0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
27af0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
27b00 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
27b10 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
27b20 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
27b30 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
27b40 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
27b50 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
27b60 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
27b70 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
27b80 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
27b90 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
27ba0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
27bb0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
27bc0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
27bd0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
27be0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
27bf0 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
27c00 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
27c10 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
27c20 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
27c30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
27c40 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
27c50 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
27c60 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
27c70 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
27c80 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
27c90 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
27ca0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
27cb0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
27cc0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
27cd0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
27ce0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
27cf0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
27d00 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
27d10 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
27d20 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
27d30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
27d40 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
27d50 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
27d60 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
27d70 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
27d80 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
27d90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
27da0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
27db0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
27dc0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
27dd0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
27de0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
27df0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
27e00 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
27e10 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
27e20 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
27e30 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
27e40 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
27e50 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
27e60 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
27e70 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
27e80 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
27e90 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
27ea0 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
27eb0 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
27ec0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
27ed0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
27ee0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
27ef0 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
27f00 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
27f10 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
27f20 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
27f30 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
27f40 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
27f50 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
27f60 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
27f70 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
27f80 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
27f90 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
27fa0 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
27fb0 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
27fc0 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
27fd0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
27fe0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
27ff0 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
28000 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
28010 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
28020 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
28030 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
28040 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
28050 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
28060 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
28070 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
28080 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
28090 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
280a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
280b0 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
280c0 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
280d0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
280e0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
280f0 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
28100 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
28110 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
28120 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
28130 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
28140 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
28150 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
28160 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
28170 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
28180 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
28190 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
281a0 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
281b0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
281c0 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
281d0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
281e0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
281f0 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
28200 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
28210 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
28220 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
28230 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
28240 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
28250 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
28260 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
28270 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
28280 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
28290 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
282a0 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
282b0 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
282c0 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
282d0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
282e0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
282f0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
28300 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
28310 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
28320 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
28330 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
28340 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
28350 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
28360 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
28370 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
28380 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
28390 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
283a0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
283b0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
283c0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
283d0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
283e0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
283f0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
28400 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
28410 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
28420 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
28430 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
28440 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
28450 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
28460 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
28470 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
28480 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
28490 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
284a0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
284b0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
284c0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
284d0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
284e0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
284f0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
28500 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
28510 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
28520 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
28530 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
28540 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
28550 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
28560 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
28570 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
28580 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
28590 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
285a0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
285b0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
285c0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
285d0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
285e0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
285f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
28600 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
28610 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
28620 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
28630 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
28640 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
28650 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
28660 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
28670 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
28680 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
28690 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
286a0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
286b0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
286c0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
286d0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
286e0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
286f0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
28700 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
28710 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
28720 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
28730 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
28740 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
28750 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
28760 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
28770 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
28780 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
28790 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
287a0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
287b0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
287c0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
287d0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
287e0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
287f0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
28800 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
28810 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
28820 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
28830 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
28840 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
28850 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
28860 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
28870 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
28880 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
28890 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
288a0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
288b0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
288c0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
288d0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
288e0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
288f0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
28900 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
28910 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
28920 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
28930 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
28940 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
28950 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
28960 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
28970 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
28980 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
28990 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
289a0 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
289b0 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
289c0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
289d0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
289e0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
289f0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
28a00 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
28a10 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
28a20 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
28a30 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
28a40 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
28a50 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
28a60 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
28a70 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
28a80 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
28a90 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
28aa0 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
28ab0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
28ac0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
28ad0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
28ae0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
28af0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
28b00 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
28b10 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
28b20 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
28b30 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
28b40 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
28b50 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
28b60 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
28b70 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
28b80 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
28b90 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
28ba0 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
28bb0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
28bc0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
28bd0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
28be0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
28bf0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
28c00 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
28c10 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
28c20 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
28c30 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
28c40 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
28c50 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
28c60 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
28c70 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
28c80 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
28c90 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
28ca0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
28cb0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
28cc0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
28cd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
28ce0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
28cf0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
28d00 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
28d10 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
28d20 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
28d30 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
28d40 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
28d50 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
28d60 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
28d70 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
28d80 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
28d90 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
28da0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
28db0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
28dc0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
28dd0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
28de0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
28df0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
28e00 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
28e10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
28e20 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
28e30 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
28e40 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
28e50 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
28e60 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
28e70 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
28e80 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
28e90 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
28ea0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
28eb0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
28ec0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
28ed0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
28ee0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
28ef0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
28f00 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
28f10 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
28f20 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
28f30 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
28f40 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
28f50 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
28f60 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
28f70 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
28f80 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
28f90 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
28fa0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
28fb0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
28fc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
28fd0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
28fe0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
28ff0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
29000 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
29010 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
29020 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
29030 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
29040 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
29050 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
29060 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
29070 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
29080 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
29090 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
290a0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
290b0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
290c0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
290d0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
290e0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
290f0 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
29100 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
29110 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
29120 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
29130 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
29140 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
29150 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
29160 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
29170 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
29180 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
29190 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
291a0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
291b0 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
291c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
291d0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
291e0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
291f0 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
29200 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
29210 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
29220 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
29230 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
29240 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
29250 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
29260 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
29270 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
29280 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
29290 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
292a0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
292b0 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
292c0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
292d0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
292e0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
292f0 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
29300 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
29310 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
29320 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
29330 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
29340 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
29350 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
29360 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
29370 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
29380 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
29390 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
293a0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
293b0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
293c0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
293d0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
293e0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
293f0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
29400 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
29410 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
29420 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
29430 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
29440 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
29450 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
29460 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
29470 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
29480 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
29490 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
294a0 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
294b0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
294c0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
294d0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
294e0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
294f0 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
29500 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
29510 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
29520 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
29530 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
29540 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
29550 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
29560 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
29570 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
29580 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
29590 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
295a0 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
295b0 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
295c0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
295d0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
295e0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
295f0 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
29600 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
29610 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
29620 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
29630 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
29640 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
29650 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
29660 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
29670 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
29680 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
29690 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
296a0 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
296b0 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
296c0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
296d0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
296e0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
296f0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
29700 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
29710 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
29720 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
29730 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
29740 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
29750 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
29760 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
29770 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
29780 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
29790 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
297a0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
297b0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
297c0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
297d0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
297e0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
297f0 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
29800 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
29810 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
29820 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
29830 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
29840 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
29850 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
29860 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
29870 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
29880 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
29890 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
298a0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
298b0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
298c0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
298d0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
298e0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
298f0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
29900 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
29910 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
29920 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
29930 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
29940 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
29950 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
29960 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
29970 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
29980 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
29990 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
299a0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
299b0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
299c0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
299d0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
299e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
299f0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
29a00 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
29a10 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
29a20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
29a30 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
29a40 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
29a50 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
29a60 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
29a70 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
29a80 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
29a90 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
29aa0 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
29ab0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29ac0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
29ad0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
29ae0 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
29af0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
29b00 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
29b10 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
29b20 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
29b30 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
29b40 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
29b50 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
29b60 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   The values retu
29b70 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
29b80 65 72 72 63 6f 64 65 28 29 20 61 6e 64 2f 6f 72  errcode() and/or
29b90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 74 65  .** sqlite3_exte
29ba0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 20 6d  nded_errcode() m
29bb0 69 67 68 74 20 63 68 61 6e 67 65 20 77 69 74 68  ight change with
29bc0 20 65 61 63 68 20 41 50 49 20 63 61 6c 6c 2e 0a   each API call..
29bd0 2a 2a 20 45 78 63 65 70 74 2c 20 74 68 65 72 65  ** Except, there
29be0 20 61 72 65 20 73 6f 6d 65 20 69 6e 74 65 72 66   are some interf
29bf0 61 63 65 73 20 74 68 61 74 20 61 72 65 20 67 75  aces that are gu
29c00 61 72 61 6e 74 65 65 64 20 74 6f 20 6e 65 76 65  aranteed to neve
29c10 72 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  r.** change the 
29c20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 65 72 72  value of the err
29c30 6f 72 20 63 6f 64 65 2e 20 20 54 68 65 20 65 72  or code.  The er
29c40 72 6f 72 2d 63 6f 64 65 20 70 72 65 73 65 72 76  ror-code preserv
29c50 69 6e 67 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ing.** interface
29c60 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  s are:.**.** <ul
29c70 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  >.** <li> sqlite
29c80 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 3c  3_errcode().** <
29c90 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 78 74 65  li> sqlite3_exte
29ca0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
29cb0 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65  * <li> sqlite3_e
29cc0 72 72 6d 73 67 28 29 0a 2a 2a 20 3c 6c 69 3e 20  rrmsg().** <li> 
29cd0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
29ce0 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  ().** </ul>.**.*
29cf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
29d00 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
29d10 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
29d20 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
29d30 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
29d40 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
29d50 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
29d60 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
29d70 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
29d80 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
29d90 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
29da0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
29db0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
29dc0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
29dd0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
29de0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
29df0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
29e00 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
29e10 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
29e20 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
29e30 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
29e40 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
29e50 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
29e60 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
29e70 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
29e80 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
29e90 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
29ea0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
29eb0 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
29ec0 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
29ed0 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
29ee0 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
29ef0 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
29f00 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
29f10 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
29f20 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
29f30 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
29f40 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
29f50 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
29f60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
29f70 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
29f80 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
29f90 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
29fa0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
29fb0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
29fc0 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
29fd0 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
29fe0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
29ff0 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
2a000 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
2a010 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
2a020 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
2a030 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
2a040 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
2a050 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
2a060 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
2a070 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
2a080 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
2a090 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
2a0a0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
2a0b0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
2a0c0 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
2a0d0 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
2a0e0 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
2a0f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2a100 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
2a110 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
2a120 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
2a130 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
2a140 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
2a150 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
2a160 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
2a170 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
2a180 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
2a190 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
2a1a0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
2a1b0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
2a1c0 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
2a1d0 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
2a1e0 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
2a1f0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
2a200 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
2a210 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
2a220 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
2a230 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
2a240 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2a250 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
2a260 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
2a270 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
2a280 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
2a290 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20   be set..*/.int 
2a2a0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2a2b0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
2a2c0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
2a2d0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
2a2e0 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
2a2f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
2a300 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
2a310 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2a320 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
2a330 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61  te3*);.const cha
2a340 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
2a350 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
2a360 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
2a370 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2a380 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2a390 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
2a3a0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
2a3b0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
2a3c0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
2a3d0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
2a3e0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
2a3f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
2a400 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63  at.** has been c
2a410 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e  ompiled into bin
2a420 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20  ary form and is 
2a430 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c  ready to be eval
2a440 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  uated..**.** Thi
2a450 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73  nk of each SQL s
2a460 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65  tatement as a se
2a470 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20  parate computer 
2a480 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a  program.  The.**
2a490 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
2a4a0 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64  xt is source cod
2a4b0 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73  e.  A prepared s
2a4c0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
2a4d0 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69  .** is the compi
2a4e0 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e  led object code.
2a4f0 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62    All SQL must b
2a500 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  e converted into
2a510 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73   a.** prepared s
2a520 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20  tatement before 
2a530 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a  it can be run..*
2a540 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79  *.** The life-cy
2a550 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  cle of a prepare
2a560 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
2a570 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20  ct usually goes 
2a580 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
2a590 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
2a5a0 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65  eate the prepare
2a5b0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
2a5c0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
2a5d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
2a5e0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
2a5f0 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74  lues to [paramet
2a600 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
2a610 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
2a620 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
2a630 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
2a640 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
2a650 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
2a660 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
2a670 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
2a680 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2a690 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
2a6a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2a6b0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
2a6c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
2a6d0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
2a6e0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
2a6f0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
2a700 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
2a710 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2a720 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
2a730 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2a740 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
2a750 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
2a760 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2a770 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
2a780 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2a790 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  3.**.** ^(This i
2a7a0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
2a7b0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
2a7c0 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
2a7d0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
2a7e0 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
2a7f0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
2a800 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
2a810 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2a820 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2a830 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
2a840 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
2a850 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
2a860 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
2a870 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
2a880 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
2a890 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
2a8a0 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
2a8b0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
2a8c0 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
2a8d0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
2a8e0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2a8f0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
2a900 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
2a910 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
2a920 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
2a930 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
2a940 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
2a950 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
2a960 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
2a970 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
2a980 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
2a990 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
2a9a0 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
2a9b0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
2a9c0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
2a9d0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
2a9e0 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
2a9f0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
2aa00 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
2aa10 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
2aa20 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
2aa30 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
2aa40 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
2aa50 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
2aa60 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
2aa70 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
2aa80 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
2aa90 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
2aaa0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
2aab0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
2aac0 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
2aad0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2aae0 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
2aaf0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
2ab00 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2ab10 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2ab20 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
2ab30 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
2ab40 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
2ab50 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
2ab60 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
2ab70 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
2ab80 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
2ab90 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
2aba0 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
2abb0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2abc0 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
2abd0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
2abe0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
2abf0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
2ac00 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
2ac10 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
2ac20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
2ac30 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
2ac40 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
2ac50 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
2ac60 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
2ac70 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
2ac80 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
2ac90 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
2aca0 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
2acb0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
2acc0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
2acd0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
2ace0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
2acf0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
2ad00 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
2ad10 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
2ad20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
2ad30 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
2ad40 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
2ad50 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
2ad60 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
2ad70 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
2ad80 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
2ad90 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
2ada0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
2adb0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
2adc0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
2add0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
2ade0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
2adf0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
2ae00 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
2ae10 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
2ae20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
2ae30 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
2ae40 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
2ae50 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
2ae60 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
2ae70 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
2ae80 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
2ae90 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
2aea0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
2aeb0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
2aec0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
2aed0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
2aee0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
2aef0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
2af00 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
2af10 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
2af20 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
2af30 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
2af40 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
2af50 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
2af60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2af70 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
2af80 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
2af90 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
2afa0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
2afb0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
2afc0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2afd0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
2afe0 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
2aff0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
2b000 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
2b010 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
2b020 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
2b030 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
2b040 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
2b050 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
2b060 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
2b070 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
2b080 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2b090 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
2b0a0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
2b0b0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
2b0c0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
2b0d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2b0e0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2b0f0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
2b100 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2b110 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
2b120 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
2b130 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
2b140 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
2b150 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2b160 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
2b170 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b180 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
2b190 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2b1a0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2b1b0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2b1c0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
2b1d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2b1e0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
2b1f0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2b200 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
2b210 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2b220 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
2b230 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
2b240 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
2b250 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
2b260 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2b270 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
2b280 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2b290 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
2b2a0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
2b2b0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
2b2c0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
2b2d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2b2e0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
2b2f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b300 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
2b310 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2b320 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
2b330 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
2b340 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
2b350 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2b360 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
2b370 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
2b380 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2b390 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2b3a0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
2b3b0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2b3c0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
2b3d0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
2b3e0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
2b3f0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2b400 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
2b410 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b420 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
2b430 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2b440 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
2b450 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
2b460 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
2b470 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
2b480 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
2b490 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
2b4a0 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  If [sqlite3_prep
2b4b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
2b4c0 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74  the equivalent t
2b4d0 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65  ries to allocate
2b4e0 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20   space for more 
2b4f0 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f  than this many o
2b500 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73  pcodes.** in a s
2b510 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73  ingle prepared s
2b520 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c  tatement, an SQL
2b530 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20  ITE_NOMEM error 
2b540 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
2b550 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2b560 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2b570 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
2b580 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2b590 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
2b5a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2b5b0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2b5c0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
2b5d0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
2b5e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
2b5f0 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
2b600 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2b610 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
2b620 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2b630 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
2b640 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
2b650 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
2b660 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2b670 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2b680 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
2b690 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
2b6a0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2b6b0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2b6c0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
2b6d0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
2b6e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2b6f0 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
2b700 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
2b710 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2b720 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2b730 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
2b740 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b750 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2b760 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
2b770 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
2b780 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
2b790 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
2b7a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
2b7b0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2b7c0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2b7d0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
2b7e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2b7f0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
2b800 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2b810 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
2b820 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
2b830 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2b840 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  [SQLITE_LIMIT_WO
2b850 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e  RKER_THREADS]] ^
2b860 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2b870 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2b880 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2b890 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2b8a0 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72  of auxiliary wor
2b8b0 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74  ker threads that
2b8c0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72   a single.** [pr
2b8d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b8e0 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64  ] may start.</dd
2b8f0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
2b900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2b910 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
2b920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
2b930 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b940 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2b950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b960 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2b970 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
2b980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b990 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2b9a0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2b9b0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2b9c0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
2b9d0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2b9e0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
2b9f0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2ba00 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2ba10 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
2ba20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
2ba30 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2ba40 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
2ba50 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
2ba60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
2ba70 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
2ba80 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
2ba90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2baa0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2bab0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
2bac0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
2bad0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
2bae0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
2baf0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
2bb00 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
2bb10 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
2bb20 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2bb30 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20  WORKER_THREADS  
2bb40 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a           11../*.
2bb50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
2bb60 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  pare Flags.**.**
2bb70 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2bb80 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
2bb90 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20 62  flags that can b
2bba0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  e passed into.**
2bbb0 20 22 70 72 65 70 46 6c 61 67 73 22 20 70 61 72   "prepFlags" par
2bbc0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73  ameter of the [s
2bbd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bbe0 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  3()] and.** [sql
2bbf0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2bc00 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e  3()] interfaces.
2bc10 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73  .**.** New flags
2bc20 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
2bc30 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2bc40 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
2bc50 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
2bc60 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2bc70 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  STENT]] ^(<dt>SQ
2bc80 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2bc90 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20  SISTENT</dt>.** 
2bca0 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50  <dd>The SQLITE_P
2bcb0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2bcc0 54 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74  T flag is a hint
2bcd0 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c   to the query pl
2bce0 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  anner.** that th
2bcf0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2bd00 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74  ment will be ret
2bd10 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67  ained for a long
2bd20 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f   time and.** pro
2bd30 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e  bably reused man
2bd40 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68  y times.)^ ^With
2bd50 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b  out this flag, [
2bd60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2bd70 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  v3()].** and [sq
2bd80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2bd90 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61  v3()] assume tha
2bda0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2bdb0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a  tatement will .*
2bdc0 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f  * be used just o
2bdd0 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61  nce or at most a
2bde0 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74   few times and t
2bdf0 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73  hen destroyed us
2be00 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2be10 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61  finalize()] rela
2be20 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65  tively soon. The
2be30 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
2be40 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20  ntation acts.** 
2be50 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79 20  on this hint by 
2be60 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65  avoiding the use
2be70 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d   of [lookaside m
2be80 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74  emory] so as not
2be90 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74   to.** deplete t
2bea0 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65  he limited store
2beb0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
2bec0 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65 72  mory. Future ver
2bed0 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69  sions of.** SQLi
2bee0 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68  te may act on th
2bef0 69 73 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e  is hint differen
2bf00 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  tly..** </dl>.*/
2bf10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2bf20 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2bf30 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
2bf40 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x01../*.** CAPI
2bf50 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
2bf60 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2bf70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2bf80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2bf90 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
2bfa0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
2bfb0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2bfc0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
2bfd0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73  execute an SQL s
2bfe0 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73  tatement, it mus
2bff0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
2c000 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
2c010 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
2c020 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
2c030 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72  se routines.  Or
2c040 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  , in other words
2c050 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  , these routines
2c060 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63  .** are construc
2c070 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72  tors for the [pr
2c080 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c090 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
2c0a0 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f  The preferred ro
2c0b0 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20  utine to use is 
2c0c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c0d0 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20  _v2()].  The.** 
2c0e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c0f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73  ()] interface is
2c100 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75   legacy and shou
2c110 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
2c120 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c130 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20  re_v3()] has an 
2c140 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73  extra "prepFlags
2c150 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73  " option that is
2c160 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65   used.** for spe
2c170 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a  cial purposes..*
2c180 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20  *.** The use of 
2c190 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66  the UTF-8 interf
2c1a0 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65  aces is preferre
2c1b0 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72  d, as SQLite cur
2c1c0 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61  rently.** does a
2c1d0 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67  ll parsing using
2c1e0 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46   UTF-8.  The UTF
2c1f0 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61  -16 interfaces a
2c200 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61  re provided.** a
2c210 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e  s a convenience.
2c220 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74    The UTF-16 int
2c230 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20  erfaces work by 
2c240 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a  converting the.*
2c250 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74  * input text int
2c260 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e  o UTF-8, then in
2c270 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65  voking the corre
2c280 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69  sponding UTF-8 i
2c290 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2c2a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2c2b0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
2c2c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c2d0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
2c2e0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
2c2f0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2c300 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2c310 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2c320 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
2c330 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2c340 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
2c350 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2c360 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
2c370 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
2c380 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
2c390 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
2c3a0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2c3b0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
2c3c0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
2c3d0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
2c3e0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2c3f0 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  are(), sqlite3_p
2c400 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20  repare_v2(),.** 
2c410 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2c420 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65  are_v3().** inte
2c430 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
2c440 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
2c450 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74  epare16(), sqlit
2c460 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c470 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2c480 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2c490 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
2c4a0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
2c4b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67   argument is neg
2c4c0 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c  ative, then zSql
2c4d0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
2c4e0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
2c4f0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
2c500 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69   nByte is positi
2c510 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
2c520 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2c530 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
2c540 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65  zSql.  ^If nByte
2c550 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e   is zero, then n
2c560 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  o prepared.** st
2c570 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72  atement is gener
2c580 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ated..** If the 
2c590 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61  caller knows tha
2c5a0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
2c5b0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
2c5c0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a  minated, then.**
2c5d0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
2c5e0 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  l performance ad
2c5f0 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69  vantage to passi
2c600 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
2c610 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
2c620 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2c630 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
2c640 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
2c650 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
2c660 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e   nul-terminator.
2c670 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
2c680 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
2c690 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
2c6a0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
2c6b0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
2c6c0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
2c6d0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
2c6e0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2c6f0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2c700 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
2c710 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
2c720 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
2c730 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
2c740 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
2c750 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
2c760 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
2c770 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
2c780 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
2c790 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
2c7a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2c7b0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
2c7c0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
2c7d0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
2c7e0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
2c7f0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
2c800 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
2c810 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
2c820 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
2c830 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
2c840 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
2c850 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
2c860 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
2c870 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
2c880 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
2c890 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
2c8a0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
2c8b0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
2c8c0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
2c8d0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2c8e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2c8f0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
2c900 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
2c910 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
2c920 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
2c930 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
2c940 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2c950 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
2c960 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2c970 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
2c980 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
2c990 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2c9a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
2c9b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c9c0 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  2(), sqlite3_pre
2c9d0 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74  pare_v3(), sqlit
2c9e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c9f0 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2ca00 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2ca10 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2ca20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
2ca30 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
2ca40 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69  ..** The older i
2ca50 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74  nterfaces (sqlit
2ca60 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
2ca70 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2ca80 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74  16()).** are ret
2ca90 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
2caa0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2cab0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
2cac0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
2cad0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22  .** ^In the "vX"
2cae0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2caf0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cb00 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
2cb10 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
2cb20 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2cb30 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
2cb40 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
2cb50 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
2cb60 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
2cb70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2cb80 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
2cb90 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
2cba0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
2cbb0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
2cbc0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2cbd0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2cbe0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
2cbf0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
2cc00 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
2cc10 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
2cc20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
2cc30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2cc40 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cc50 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
2cc60 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
2cc70 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
2cc80 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
2cc90 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
2cca0 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
2ccb0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
2ccc0 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
2ccd0 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
2cce0 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
2ccf0 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
2cd00 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2cd10 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
2cd20 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
2cd30 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
2cd40 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
2cd50 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
2cd60 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
2cd70 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
2cd80 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
2cd90 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
2cda0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
2cdb0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
2cdc0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
2cdd0 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
2cde0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
2cdf0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
2ce00 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
2ce10 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
2ce20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2ce30 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
2ce40 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
2ce50 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
2ce60 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
2ce70 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
2ce80 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
2ce90 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
2cea0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
2ceb0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
2cec0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
2ced0 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
2cee0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2cef0 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
2cf00 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
2cf10 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
2cf20 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2cf30 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2cf40 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2cf50 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
2cf60 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
2cf70 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
2cf80 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
2cf90 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
2cfa0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2cfb0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
2cfc0 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
2cfd0 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
2cfe0 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
2cff0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2d000 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
2d010 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
2d020 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
2d030 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
2d040 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
2d050 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
2d060 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
2d070 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
2d080 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
2d090 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
2d0a0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2d0b0 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
2d0c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
2d0d0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
2d0e0 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
2d0f0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
2d100 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2d110 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
2d120 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
2d130 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
2d140 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
2d150 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
2d160 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
2d170 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ed..** </li>.** 
2d180 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e  </ol>.**.** <p>^
2d190 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d1a0 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72 6f  v3() differs fro
2d1b0 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  m sqlite3_prepar
2d1c0 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68  e_v2() only in h
2d1d0 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74  aving.** the ext
2d1e0 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61 72  ra prepFlags par
2d1f0 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69 73  ameter, which is
2d200 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e   a bit array con
2d210 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20  sisting of zero 
2d220 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  or.** more of th
2d230 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52  e [SQLITE_PREPAR
2d240 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c  E_PERSISTENT|SQL
2d250 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66  ITE_PREPARE_*] f
2d260 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  lags.  ^The.** s
2d270 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d280 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
2d290 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65 20  rks exactly the 
2d2a0 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
2d2b0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20  e3_prepare_v3() 
2d2c0 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70  with a zero prep
2d2d0 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e  Flags parameter.
2d2e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2d2f0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
2d300 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2d310 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2d320 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2d330 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2d340 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2d350 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2d360 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2d370 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2d380 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2d390 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2d3a0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2d3b0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2d3c0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2d3d0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2d3e0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2d3f0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2d400 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2d410 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2d420 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2d430 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
2d440 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2d450 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2d460 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2d470 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2d480 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2d490 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2d4a0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2d4b0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2d4c0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2d4d0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2d4e0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2d4f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2d500 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2d510 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2d520 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2d530 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2d540 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2d550 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2d560 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2d570 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d580 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2d590 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2d5a0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2d5b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2d5c0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2d5d0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2d5e0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2d5f0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2d600 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2d610 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2d620 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2d630 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e  */.  unsigned in
2d640 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20  t prepFlags, /* 
2d650 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c  Zero or more SQL
2d660 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61  ITE_PREPARE_ fla
2d670 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  gs */.  sqlite3_
2d680 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2d690 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2d6a0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2d6b0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2d6c0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2d6d0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2d6e0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2d6f0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2d700 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2d710 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2d720 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2d730 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2d740 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2d750 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2d760 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2d770 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2d780 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2d790 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2d7a0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2d7b0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2d7c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2d7d0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2d7e0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2d7f0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2d800 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2d810 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2d820 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2d830 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2d840 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d850 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
2d860 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2d870 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2d880 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2d890 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2d8a0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2d8b0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2d8c0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2d8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2d8e0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2d8f0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2d900 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2d910 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2d920 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2d930 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2d940 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2d950 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2d960 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2d970 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2d980 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2d990 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20  _prepare16_v3(. 
2d9a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2d9b0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2d9c0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2d9d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2d9e0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2d9f0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2da00 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2da10 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2da20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2da30 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2da40 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2da50 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65  unsigned int pre
2da60 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20  pFlags, /* Zero 
2da70 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50  or more SQLITE_P
2da80 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f  REPARE_ flags */
2da90 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2daa0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2dab0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2dac0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2dad0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2dae0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2daf0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2db00 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2db10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2db20 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
2db30 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
2db40 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2db50 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2db60 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74  lite3_sql(P) int
2db70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2db80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
2db90 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a  py of the UTF-8.
2dba0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
2dbb0 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70   to create [prep
2dbc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2dbd0 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72  P if P was.** cr
2dbe0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
2dbf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2dc00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dc10 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v3()],.** [sql
2dc20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2dc30 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  2()], or [sqlite
2dc40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2dc50 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
2dc60 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2dc70 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2dc80 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2dc90 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2dca0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2dcb0 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70  he SQL text of p
2dcc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dcd0 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75  t P with.** [bou
2dce0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65  nd parameters] e
2dcf0 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  xpanded..**.** ^
2dd00 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2dd10 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2dd20 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64  ement is created
2dd30 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a   using the SQL.*
2dd40 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24  * text "SELECT $
2dd50 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66  abc,:xyz" and if
2dd60 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20   parameter $abc 
2dd70 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65  is bound to inte
2dd80 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20  ger 2345.** and 
2dd90 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69  parameter :xyz i
2dda0 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20  s unbound, then 
2ddb0 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69  sqlite3_sql() wi
2ddc0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  ll return.** the
2ddd0 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67   original string
2dde0 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  , "SELECT $abc,:
2ddf0 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33  xyz" but sqlite3
2de00 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a  _expanded_sql().
2de10 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22  ** will return "
2de20 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c  SELECT 2345,NULL
2de30 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ".)^.**.** ^The 
2de40 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2de50 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65  _sql() interface
2de60 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
2de70 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
2de80 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c  mory.** is avail
2de90 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65  able to hold the
2dea0 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74   result, or if t
2deb0 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20  he result would 
2dec0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68  exceed the.** th
2ded0 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67  e maximum string
2dee0 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e   length determin
2def0 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ed by the [SQLIT
2df00 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e  E_LIMIT_LENGTH].
2df10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
2df20 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
2df30 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
2df40 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73  me option limits
2df50 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
2df60 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
2df70 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68  expansions.  ^Th
2df80 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54  e [SQLITE_OMIT_T
2df90 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
2dfa0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75  me.** option cau
2dfb0 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61  ses sqlite3_expa
2dfc0 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c  nded_sql() to al
2dfd0 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ways return NULL
2dfe0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72  ..**.** ^The str
2dff0 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
2e000 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69  sqlite3_sql(P) i
2e010 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c  s managed by SQL
2e020 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75  ite and is.** au
2e030 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
2e040 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61  d when the prepa
2e050 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
2e060 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e   finalized..** ^
2e070 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2e080 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65  ned by sqlite3_e
2e090 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20  xpanded_sql(P), 
2e0a0 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e  on the other han
2e0b0 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65  d,.** is obtaine
2e0c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2e0d0 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75  malloc()] and mu
2e0e0 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68  st be free by th
2e0f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
2e100 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74   by passing it t
2e110 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
2e120 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
2e130 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
2e140 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2e150 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  mt);.char *sqlit
2e160 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2e170 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2e180 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2e190 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2e1a0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2e1b0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2e1c0 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
2e1d0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e1e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e1f0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2e200 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
2e210 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2e220 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
2e230 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
2e240 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e250 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
2e260 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
2e270 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
2e280 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2e290 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
2e2a0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
2e2b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2e2c0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
2e2d0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
2e2e0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
2e2f0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
2e300 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
2e310 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
2e320 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
2e330 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2e340 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
2e350 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
2e360 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
2e370 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
2e380 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
2e390 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
2e3a0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
2e3b0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
2e3c0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
2e3d0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2e3e0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
2e3f0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
2e400 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
2e410 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
2e420 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2e430 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
2e440 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2e450 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2e460 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2e470 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
2e480 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
2e490 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
2e4a0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
2e4b0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
2e4c0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
2e4d0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
2e4e0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
2e4f0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
2e500 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
2e510 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
2e520 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
2e530 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2e540 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2e550 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
2e560 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
2e570 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
2e580 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
2e590 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
2e5a0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
2e5b0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
2e5c0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
2e5d0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
2e5e0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
2e5f0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
2e600 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
2e610 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
2e620 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
2e630 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2e640 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
2e650 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
2e660 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
2e670 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
2e680 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
2e690 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
2e6a0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
2e6b0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
2e6c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2e6d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2e6e0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e  es on disk..** ^
2e6f0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2e700 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65  _readonly() inte
2e710 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2e720 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73  ue for [BEGIN] s
2e730 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20  ince.** [BEGIN] 
2e740 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65  merely sets inte
2e750 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20  rnal flags, but 
2e760 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  the [BEGIN|BEGIN
2e770 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a   IMMEDIATE] and.
2e780 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  ** [BEGIN|BEGIN 
2e790 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61  EXCLUSIVE] comma
2e7a0 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65  nds do touch the
2e7b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f   database and so
2e7c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2e7d0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75  _readonly() retu
2e7e0 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68  rns false for th
2e7f0 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f  ose commands..*/
2e800 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2e810 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
2e820 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2e830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e840 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2e850 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2e860 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
2e870 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2e880 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e890 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2e8a0 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2e8b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2e8c0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2e8d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2e8e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2e8f0 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2e900 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2e910 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2e920 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2e930 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
2e940 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
2e950 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2e960 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
2e970 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
2e980 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
2e990 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2e9a0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2e9b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2e9c0 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2e9d0 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2e9e0 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2e9f0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2ea00 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2ea10 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2ea20 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2ea30 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2ea40 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2ea50 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2ea60 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2ea70 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2ea80 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2ea90 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2eaa0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2eab0 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2eac0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2ead0 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2eae0 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2eaf0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2eb00 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2eb10 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2eb20 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2eb30 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2eb40 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2eb50 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2eb60 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2eb70 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2eb80 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2eb90 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2eba0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2ebb0 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2ebc0 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
2ebd0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2ebe0 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2ebf0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2ec00 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2ec10 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2ec20 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2ec30 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2ec40 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2ec50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ec60 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2ec70 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2ec80 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2ec90 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2eca0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2ecb0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2ecc0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2ecd0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2ece0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2ecf0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2ed00 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2ed10 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2ed20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2ed30 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2ed40 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2ed50 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2ed60 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2ed70 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2ed80 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2ed90 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2eda0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2edb0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2edc0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2edd0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2ede0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2edf0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2ee00 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2ee10 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2ee20 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2ee30 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2ee40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2ee50 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2ee60 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2ee70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2ee80 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2ee90 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2eea0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2eeb0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2eec0 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2eed0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2eee0 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2eef0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2ef00 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2ef10 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2ef20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2ef30 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2ef40 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2ef50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2ef60 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2ef70 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2ef80 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2ef90 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2efa0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2efb0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2efc0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2efd0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2efe0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2eff0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2f000 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2f010 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2f020 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2f030 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2f040 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2f050 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2f060 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2f070 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2f080 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2f090 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2f0a0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2f0b0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2f0c0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2f0d0 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2f0e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2f0f0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2f100 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2f110 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2f120 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2f130 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2f140 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2f150 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2f160 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2f170 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2f180 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2f190 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2f1a0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2f1b0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2f1c0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2f1d0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2f1e0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2f1f0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2f200 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2f210 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2f220 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2f230 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2f240 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2f250 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2f260 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2f270 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f280 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2f290 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2f2a0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2f2b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f2c0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2f2d0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2f2e0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2f2f0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2f300 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2f310 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2f320 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2f330 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2f340 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2f350 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f360 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2f370 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2f380 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a   as arguments.**
2f390 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2f3a0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73  ult_value()], [s
2f3b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2f3c0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2f3d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2f3e0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
2f3f0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
2f400 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2f410 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
2f420 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
2f430 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
2f440 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f450 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
2f460 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2f470 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
2f480 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2f490 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2f4a0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2f4b0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2f4c0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2f4d0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2f4e0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2f4f0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2f500 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2f510 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2f520 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2f530 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2f540 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2f550 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2f560 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f570 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2f580 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2f590 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2f5a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2f5b0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2f5c0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2f5d0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2f5e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2f5f0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2f600 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2f610 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2f620 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2f630 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2f640 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2f650 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2f660 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2f670 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2f680 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2f690 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2f6a0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2f6b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2f6c0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2f6d0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2f6e0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2f6f0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2f700 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2f710 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2f720 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2f730 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2f740 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2f750 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2f760 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2f770 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2f780 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2f790 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2f7a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2f7b0 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2f7c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2f7d0 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2f7e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f7f0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2f800 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2f810 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2f820 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2f830 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2f840 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2f850 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2f860 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2f870 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2f880 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2f890 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2f8a0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2f8b0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2f8c0 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2f8d0 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2f8e0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2f8f0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2f900 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2f910 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2f920 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2f930 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2f940 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2f950 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2f960 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2f970 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2f980 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2f990 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2f9a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2f9b0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2f9c0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2f9d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2f9e0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2f9f0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2fa00 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2fa10 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2fa20 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2fa30 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2fa40 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2fa50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2fa60 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2fa70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2fa80 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2fa90 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2faa0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2fab0 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2fac0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2fad0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2fae0 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2faf0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2fb00 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2fb10 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2fb20 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2fb30 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2fb40 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2fb50 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2fb60 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2fb70 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2fb80 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2fb90 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2fba0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2fbb0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2fbc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2fbd0 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2fbe0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2fbf0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2fc00 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2fc10 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2fc20 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2fc30 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2fc40 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2fc50 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2fc60 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2fc70 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2fc80 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2fc90 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2fca0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2fcb0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2fcc0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2fcd0 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2fce0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2fcf0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2fd00 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2fd10 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2fd20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2fd30 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2fd40 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2fd50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2fd60 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2fd70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2fd80 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2fd90 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2fda0 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2fdb0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2fdc0 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2fdd0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2fde0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2fdf0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2fe00 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2fe10 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2fe20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2fe30 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2fe40 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2fe50 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2fe60 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2fe70 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2fe80 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2fe90 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2fea0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2feb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2fec0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2fed0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2fee0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2fef0 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2ff00 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2ff10 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2ff20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2ff30 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2ff40 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2ff50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2ff60 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2ff70 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2ff80 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2ff90 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2ffa0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2ffb0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2ffc0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2ffd0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2ffe0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2fff0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
30000 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
30010 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
30020 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
30030 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
30040 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
30050 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
30060 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
30070 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
30080 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
30090 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
300a0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
300b0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
300c0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
300d0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
300e0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
300f0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
30100 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
30110 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
30120 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
30130 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
30140 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
30150 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
30160 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
30170 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
30180 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
30190 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
301a0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
301b0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
301c0 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
301d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
301e0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
301f0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
30200 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
30210 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
30220 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
30230 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
30240 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
30250 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
30260 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
30270 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
30280 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
30290 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
302a0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
302b0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
302c0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
302d0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
302e0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
302f0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
30300 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
30310 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
30320 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
30330 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
30340 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
30350 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
30360 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
30370 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
30380 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
30390 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
303a0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
303b0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
303c0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
303d0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
303e0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
303f0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
30400 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
30410 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
30420 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
30430 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
30440 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
30450 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
30460 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
30470 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
30480 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
30490 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
304a0 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
304b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
304c0 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
304d0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
304e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
304f0 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
30500 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
30510 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
30520 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
30530 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
30540 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
30550 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
30560 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
30570 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
30580 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
30590 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
305a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
305b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
305c0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
305d0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
305e0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
305f0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
30600 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
30610 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
30620 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
30630 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
30640 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
30650 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
30660 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
30670 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
30680 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
30690 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
306a0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
306b0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
306c0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
306d0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
306e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
306f0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
30700 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
30710 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
30720 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
30730 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
30740 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
30750 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   BLOB..**.** ^Th
30760 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
30770 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44  ointer(S,I,P,T,D
30780 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73  ) routine causes
30790 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65   the I-th parame
307a0 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61  ter in.** [prepa
307b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
307c0 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20   to have an SQL 
307d0 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62  value of NULL, b
307e0 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a  ut to also be.**
307f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
30800 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f   the pointer P o
30810 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73  f type T.  ^D is
30820 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
30830 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70  ointer or.** a p
30840 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
30850 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
30860 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77  for P. ^SQLite w
30870 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a  ill invoke the.*
30880 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  * destructor D w
30890 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
308a0 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20  ument of P when 
308b0 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20 75  it is finished u
308c0 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20  sing.** P.  The 
308d0 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  T parameter shou
308e0 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20 73  ld be a static s
308f0 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c  tring, preferabl
30900 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69  y a string.** li
30910 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74  teral. The sqlit
30920 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
30930 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72  ) routine is par
30940 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69  t of the.** [poi
30950 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74  nter passing int
30960 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f  erface] added fo
30970 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e  r SQLite 3.20.0.
30980 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
30990 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
309a0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
309b0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
309c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
309d0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
309e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
309f0 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
30a00 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
30a10 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
30a20 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
30a30 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
30a40 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
30a50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
30a60 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
30a70 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
30a80 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
30a90 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
30aa0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
30ab0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
30ac0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30ad0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
30ae0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
30af0 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
30b00 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
30b10 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
30b20 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
30b30 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
30b40 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
30b50 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
30b60 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
30b70 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
30b80 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
30b90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30ba0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
30bb0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
30bc0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
30bd0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
30be0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
30bf0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
30c00 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
30c10 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
30c20 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
30c30 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
30c40 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
30c50 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
30c60 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
30c70 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
30c80 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
30c90 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
30ca0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
30cb0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
30cc0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
30cd0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
30ce0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
30cf0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
30d00 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
30d10 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
30d20 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
30d30 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30d40 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
30d50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30d60 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
30d70 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
30d80 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
30d90 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
30da0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30db0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30dc0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
30dd0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
30de0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
30df0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
30e00 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
30e10 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
30e20 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
30e30 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
30e40 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
30e50 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
30e60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
30e70 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
30e80 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
30e90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30ea0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
30eb0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
30ec0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30ed0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
30ee0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
30ef0 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
30f00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
30f10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30f20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
30f30 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
30f40 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
30f50 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
30f60 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
30f70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30f80 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
30f90 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
30fa0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
30fb0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
30fc0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
30fd0 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
30fe0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
30ff0 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
31000 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
31010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31020 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
31030 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
31040 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
31050 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
31060 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31070 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
31080 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
31090 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
310a0 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ter(sqlite3_stmt
310b0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63  *, int, void*, c
310c0 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 28  onst char*,void(
310d0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
310e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
310f0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
31100 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
31110 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
31120 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  nd_zeroblob64(sq
31130 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31140 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
31150 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31160 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
31170 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
31180 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
31190 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
311a0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
311b0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
311c0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
311d0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
311e0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
311f0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
31200 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
31210 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
31220 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
31230 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
31240 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
31250 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
31260 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
31270 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
31280 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
31290 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
312a0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
312b0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
312c0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
312d0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
312e0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
312f0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
31300 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
31310 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
31320 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
31330 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
31340 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
31350 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
31360 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
31370 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
31380 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
31390 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
313a0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
313b0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
313c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
313d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
313e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
313f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
31400 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
31410 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
31420 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
31430 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
31440 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
31450 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
31460 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
31470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31480 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
31490 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
314a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
314b0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
314c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
314d0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
314e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
314f0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
31500 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
31510 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
31520 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31530 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
31540 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
31550 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
31560 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
31570 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
31580 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
31590 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
315a0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
315b0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
315c0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
315d0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
315e0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
315f0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
31600 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
31610 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
31620 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
31630 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
31640 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
31650 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
31660 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
31670 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
31680 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
31690 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
316a0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
316b0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
316c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
316d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
316e0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
316f0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
31700 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
31710 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
31720 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
31730 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
31740 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
31750 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
31760 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
31770 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
31780 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
31790 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
317a0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
317b0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
317c0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
317d0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
317e0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a  prepare16()],.**
317f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31800 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73  e16_v2()], or [s
31810 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
31820 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v3()]..**.** Se
31830 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
31840 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
31850 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
31860 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
31870 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
31880 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
31890 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
318a0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
318b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
318c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
318d0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
318e0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
318f0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
31900 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
31910 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
31920 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
31930 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31940 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
31950 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
31960 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
31970 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
31980 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
31990 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
319a0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
319b0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
319c0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
319d0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
319e0 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
319f0 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
31a00 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
31a10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
31a20 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
31a30 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
31a40 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
31a50 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
31a60 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
31a70 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
31a80 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
31a90 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
31aa0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
31ab0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
31ac0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
31ad0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
31ae0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
31af0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
31b00 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
31b10 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
31b20 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
31b30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
31b40 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
31b50 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
31b60 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
31b70 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
31b80 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
31b90 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
31ba0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
31bb0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
31bc0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
31bd0 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
31be0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31bf0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
31c00 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
31c10 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
31c20 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
31c30 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
31c40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
31c50 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
31c60 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
31c70 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
31c80 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
31c90 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
31ca0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
31cb0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
31cc0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
31cd0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
31ce0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
31cf0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
31d00 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
31d10 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
31d20 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31d30 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
31d40 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
31d50 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
31d60 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
31d70 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
31d80 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49  d statement]. ^I
31d90 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
31da0 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d  eturns 0, that m
31db0 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72  eans the .** [pr
31dc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31dd0 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74  ] returns no dat
31de0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
31df0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20  n [UPDATE])..** 
31e00 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62  ^However, just b
31e10 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74  ecause this rout
31e20 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
31e30 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f  sitive number do
31e40 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74  es not.** mean t
31e50 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  hat one or more 
31e60 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c  rows of data wil
31e70 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  l be returned.  
31e80 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  ^A SELECT statem
31e90 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  ent.** will alwa
31ea0 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69  ys have a positi
31eb0 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ve sqlite3_colum
31ec0 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65  n_count() but de
31ed0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a  pending on the.*
31ee0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  * WHERE clause c
31ef0 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
31f00 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74  he table content
31f10 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72  , it might retur
31f20 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a  n no rows..**.**
31f30 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
31f40 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
31f50 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
31f60 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
31f70 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
31f80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31f90 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
31fa0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
31fb0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31fc0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31fd0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
31fe0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
31ff0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
32000 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
32010 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
32020 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
32030 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
32040 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
32050 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
32060 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
32070 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
32080 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
32090 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
320a0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
320b0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
320c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
320d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
320e0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
320f0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
32100 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
32110 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32120 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
32130 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
32140 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
32150 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
32160 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
32170 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
32180 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
32190 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
321a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
321b0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
321c0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
321d0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
321e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
321f0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
32200 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
32210 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
32220 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
32230 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
32240 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
32250 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
32260 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
32270 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
32280 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
32290 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
322a0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
322b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
322c0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
322d0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
322e0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
322f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
32300 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
32310 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
32320 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
32330 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
32340 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
32350 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
32360 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
32370 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
32380 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
32390 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
323a0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
323b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
323c0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
323d0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
323e0 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
323f0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
32400 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
32410 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
32420 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
32430 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
32440 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
32450 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
32460 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
32470 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
32480 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
32490 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
324a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
324b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
324c0 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
324d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
324e0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
324f0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
32500 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32510 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
32520 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
32530 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32540 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
32550 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
32560 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
32570 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
32580 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
32590 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
325a0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
325b0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
325c0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
325d0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
325e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
325f0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
32600 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
32610 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
32620 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
32630 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
32640 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
32650 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
32660 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
32670 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
32680 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
32690 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
326a0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
326b0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
326c0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
326d0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
326e0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
326f0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
32700 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
32710 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
32720 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
32730 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
32740 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
32750 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
32760 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
32770 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
32780 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
32790 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
327a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
327b0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
327c0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
327d0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
327e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
327f0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
32800 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
32810 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
32820 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
32830 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
32840 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
32850 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
32860 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
32870 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
32880 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
32890 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
328a0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
328b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
328c0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
328d0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
328e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
328f0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
32900 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
32910 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
32920 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
32930 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
32940 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
32950 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
32960 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
32970 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
32980 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
32990 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
329a0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
329b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
329c0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
329d0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
329e0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
329f0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
32a00 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
32a10 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
32a20 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
32a30 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
32a40 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
32a50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
32a60 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
32a70 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
32a80 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
32a90 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
32aa0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
32ab0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
32ac0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
32ad0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
32ae0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
32af0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
32b00 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
32b10 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
32b20 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
32b30 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
32b40 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
32b50 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
32b60 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
32b70 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
32b80 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
32b90 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
32ba0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
32bb0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
32bc0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
32bd0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
32be0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
32bf0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
32c00 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
32c10 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
32c20 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
32c30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
32c40 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
32c50 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
32c60 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
32c70 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
32c80 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
32c90 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
32ca0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
32cb0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
32cc0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
32cd0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
32ce0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
32cf0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
32d00 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
32d10 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
32d20 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
32d30 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
32d40 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
32d50 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
32d60 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
32d70 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
32d80 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
32d90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
32da0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
32db0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
32dc0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32dd0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
32de0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
32df0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
32e00 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32e10 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
32e20 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
32e30 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
32e40 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
32e50 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
32e60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
32e70 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
32e80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
32e90 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
32ea0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
32eb0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32ec0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
32ed0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
32ee0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
32ef0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
32f00 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
32f10 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
32f20 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
32f30 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
32f40 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
32f50 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
32f60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
32f70 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
32f80 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
32f90 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
32fa0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
32fb0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
32fc0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
32fd0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
32fe0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
32ff0 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
33000 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
33010 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
33020 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
33030 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
33040 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
33050 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
33060 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
33070 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
33080 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
33090 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
330a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
330b0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
330c0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
330d0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
330e0 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
330f0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
33100 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
33110 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
33120 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
33130 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
33140 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
33150 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
33160 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
33170 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
33180 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
33190 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
331a0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
331b0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
331c0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
331d0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
331e0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
331f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
33200 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
33210 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
33220 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
33230 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
33240 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
33250 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
33260 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
33270 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
33280 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
33290 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
332a0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
332b0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
332c0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
332d0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
332e0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
332f0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
33300 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
33310 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
33320 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
33330 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
33340 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
33350 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
33360 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
33370 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
33380 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
33390 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
333a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
333b0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
333c0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
333d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
333e0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
333f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
33400 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
33410 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
33420 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
33430 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
33440 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
33450 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
33460 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
33470 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
33480 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71  ng any of.** [sq
33490 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
334a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
334b0 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
334c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
334d0 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  v2()],.** or [sq
334e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
334f0 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v3()] or one of 
33500 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
33510 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
33520 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
33530 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33540 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
33550 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
33560 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
33570 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
33580 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
33590 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
335a0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
335b0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
335c0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
335d0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
335e0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
335f0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
33600 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
33610 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65 72  newer "vX" inter
33620 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  faces.** [sqlite
33630 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
33640 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33650 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
33660 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
33670 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
33680 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
33690 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
336a0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
336b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
336c0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
336d0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
336e0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
336f0 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65  ** new "vX" inte
33700 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
33710 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
33720 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
33730 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
33740 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
33750 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
33760 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
33770 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
33780 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
33790 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
337a0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
337b0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
337c0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
337d0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
337e0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
337f0 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
33800 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
33810 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
33820 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
33830 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
33840 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
33850 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
33860 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
33870 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
33880 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
33890 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
338a0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
338b0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
338c0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
338d0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
338e0 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
338f0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
33900 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
33910 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
33920 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
33930 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
33940 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
33950 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
33960 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
33970 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
33980 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
33990 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
339a0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
339b0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
339c0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
339d0 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
339e0 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
339f0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
33a00 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
33a10 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
33a20 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
33a30 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
33a40 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
33a50 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
33a60 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
33a70 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
33a80 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
33a90 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
33aa0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33ab0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
33ac0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
33ad0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
33ae0 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
33af0 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
33b00 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
33b10 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
33b20 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
33b30 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
33b40 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
33b50 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
33b60 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
33b70 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
33b80 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
33b90 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
33ba0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
33bb0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
33bc0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
33bd0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
33be0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
33bf0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
33c00 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
33c10 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
33c20 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
33c30 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
33c40 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
33c50 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
33c60 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
33c70 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
33c80 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
33c90 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
33ca0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
33cb0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
33cc0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
33cd0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
33ce0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
33cf0 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
33d00 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
33d10 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
33d20 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
33d30 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
33d40 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
33d50 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
33d60 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
33d70 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
33d80 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
33d90 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
33da0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
33db0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
33dc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
33dd0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
33de0 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
33df0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
33e00 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
33e10 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
33e20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
33e30 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
33e40 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
33e50 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
33e60 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
33e70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
33e80 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
33e90 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
33ea0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33eb0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
33ec0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
33ed0 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
33ee0 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
33ef0 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
33f00 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
33f10 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
33f20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
33f30 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
33f40 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
33f50 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
33f60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33f70 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
33f80 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
33f90 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
33fa0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
33fb0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
33fc0 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
33fd0 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
33fe0 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
33ff0 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
34000 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34010 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
34020 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
34030 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
34040 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
34050 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
34060 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
34070 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
34080 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
34090 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
340a0 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
340b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
340c0 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
340d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
340e0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
340f0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
34100 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
34110 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
34120 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73   But after [vers
34130 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b  ion 3.6.23.1] ([
34140 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d  dateof:3.6.23.1]
34150 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ,.** sqlite3_ste
34160 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
34170 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
34180 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
34190 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
341a0 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
341b0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
341c0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
341d0 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
341e0 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
341f0 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
34200 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
34210 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
34220 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
34230 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
34240 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
34250 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
34260 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
34270 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
34280 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
34290 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
342a0 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
342b0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
342c0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
342d0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
342e0 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
342f0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
34300 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
34310 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
34320 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
34330 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
34340 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
34350 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
34360 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
34370 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
34380 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
34390 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
343a0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
343b0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
343c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
343d0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
343e0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
343f0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
34400 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
34410 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
34420 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
34430 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
34440 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
34450 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
34460 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
34470 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
34480 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
34490 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
344a0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
344b0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ts.** using [sql
344c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
344d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
344e0 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
344f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
34500 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b  are16_v2()] or [
34510 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
34520 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v3()] instead.
34530 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
34540 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34550 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
34560 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
34570 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
34580 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
34590 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
345a0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
345b0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
345c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
345d0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
345e0 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20 69  vX" interfaces i
345f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
34600 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
34610 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
34620 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34630 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
34640 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
34650 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
34660 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
34670 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34680 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
34690 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
346a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
346b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
346c0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
346d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
346e0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
346f0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
34700 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
34710 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
34720 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
34730 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
34740 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
34750 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
34760 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
34770 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
34780 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
34790 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
347a0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
347b0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
347c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
347d0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
347e0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
347f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
34800 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34810 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
34820 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
34830 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
34840 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
34850 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
34860 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
34870 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
34880 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
34890 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
348a0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
348b0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
348c0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
348d0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
348e0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
348f0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
34900 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
34910 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
34920 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
34930 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
34940 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
34950 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
34960 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
34970 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
34980 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
34990 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
349a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
349b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
349c0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
349d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
349e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
349f0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
34a00 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
34a10 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
34a20 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
34a30 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
34a40 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
34a50 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
34a60 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
34a70 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
34a80 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
34a90 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
34aa0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
34ab0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
34ac0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
34ad0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
34ae0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
34af0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
34b00 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
34b10 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
34b20 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
34b30 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
34b40 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
34b50 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
34b60 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
34b70 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
34b80 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
34b90 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
34ba0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
34bb0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
34bc0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
34bd0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
34be0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
34bf0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
34c00 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
34c10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
34c20 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
34c30 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
34c40 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
34c50 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
34c60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
34c70 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
34c80 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
34c90 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
34ca0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
34cb0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
34cc0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
34cd0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
34ce0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
34cf0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
34d00 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
34d10 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
34d20 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
34d30 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
34d40 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
34d50 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a  *.** <b>Summary:
34d60 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  </b>.** <blockqu
34d70 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65  ote><table borde
34d80 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  r=0 cellpadding=
34d90 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e  0 cellspacing=0>
34da0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34db0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
34dc0 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ob</b><td>&rarr;
34dd0 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a  <td>BLOB result.
34de0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
34df0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
34e00 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  ble</b><td>&rarr
34e10 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74  ;<td>REAL result
34e20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34e30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
34e40 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  t</b><td>&rarr;<
34e50 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45  td>32-bit INTEGE
34e60 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  R result.** <tr>
34e70 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
34e80 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c  olumn_int64</b><
34e90 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d  td>&rarr;<td>64-
34ea0 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75  bit INTEGER resu
34eb0 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
34ec0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34ed0 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  text</b><td>&rar
34ee0 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54  r;<td>UTF-8 TEXT
34ef0 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
34f00 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
34f10 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c  lumn_text16</b><
34f20 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46  td>&rarr;<td>UTF
34f30 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a  -16 TEXT result.
34f40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
34f50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
34f60 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  ue</b><td>&rarr;
34f70 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61  <td>The result a
34f80 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  s an .** [sqlite
34f90 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63  3_value|unprotec
34fa0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34fb0 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74  e] object..** <t
34fc0 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e  r><td>&nbsp;<td>
34fd0 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b  &nbsp;<td>&nbsp;
34fe0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34ff0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35000 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  tes</b><td>&rarr
35010 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42  ;<td>Size of a B
35020 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d  LOB.** or a UTF-
35030 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e  8 TEXT result in
35040 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74   bytes.** <tr><t
35050 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
35060 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70  umn_bytes16&nbsp
35070 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c  ;&nbsp;</b>.** <
35080 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26  td>&rarr;&nbsp;&
35090 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  nbsp;<td>Size of
350a0 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20   UTF-16.** TEXT 
350b0 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e  in bytes.** <tr>
350c0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
350d0 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74  olumn_type</b><t
350e0 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61  d>&rarr;<td>Defa
350f0 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20  ult.** datatype 
35100 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  of the result.**
35110 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b   </table></block
35120 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  quote>.**.** <b>
35130 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a  Details:</b>.**.
35140 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
35150 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
35160 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
35170 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
35180 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
35190 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
351a0 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
351b0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
351c0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
351d0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
351e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
351f0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
35200 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
35210 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
35220 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
35230 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
35240 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
35250 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
35260 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
35270 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
35280 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
35290 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
352a0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
352b0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
352c0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
352d0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
352e0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
352f0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
35300 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
35310 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
35320 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
35330 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
35340 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
35350 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
35360 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
35370 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
35380 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
35390 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
353a0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
353b0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
353c0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
353d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
353e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
353f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
35400 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
35410 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
35420 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
35430 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
35440 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
35450 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
35460 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
35470 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
35480 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
35490 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
354a0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
354b0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
354c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
354d0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
354e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
354f0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
35500 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
35510 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
35520 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
35530 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
35540 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
35550 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
35560 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
35570 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
35580 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
35590 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
355a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
355b0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
355c0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
355d0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
355e0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
355f0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
35600 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
35610 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
35620 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
35630 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20 69   The first six i
35640 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62  nterfaces (_blob
35650 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c  , _double, _int,
35660 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20   _int64, _text, 
35670 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20  and _text16).** 
35680 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65 20  each return the 
35690 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c  value of a resul
356a0 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70  t column in a sp
356b0 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d  ecific data form
356c0 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72  at.  If.** the r
356d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
356e0 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e  not initially in
356f0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 66   the requested f
35700 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70  ormat (for examp
35710 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75  le,.** if the qu
35720 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ery returns an i
35730 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20 73  nteger but the s
35740 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35750 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  xt() interface.*
35760 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78 74  * is used to ext
35770 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29 20  ract the value) 
35780 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69  then an automati
35790 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  c type conversio
357a0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
357b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
357c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
357d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
357e0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
357f0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
35800 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
35810 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
35820 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
35830 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
35840 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
35850 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
35860 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
35870 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
35880 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
35890 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
358a0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a   [SQLITE_NULL]..
358b0 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  ** The return va
358c0 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  lue of sqlite3_c
358d0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e  olumn_type() can
358e0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63 69   be used to deci
358f0 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74  de which.** of t
35900 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74  he first six int
35910 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65  erface should be
35920 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74   used to extract
35930 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75   the column valu
35940 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  e..** The value 
35950 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
35960 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
35970 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
35980 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75  gful if no.** au
35990 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e  tomatic type con
359a0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
359b0 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20 76  curred for the v
359c0 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e  alue in question
359d0 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74  .  .** After a t
359e0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20  ype conversion, 
359f0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61  the result of ca
35a00 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  lling sqlite3_co
35a10 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69  lumn_type().** i
35a20 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f  s undefined, tho
35a30 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46  ugh harmless.  F
35a40 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
35a50 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
35a60 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
35a70 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
35a80 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
35a90 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
35aa0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
35ab0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
35ac0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20   is a BLOB or a 
35ad0 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65  TEXT string, the
35ae0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
35af0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
35b00 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
35b10 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74 65  n_bytes16() inte
35b20 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75 73  rfaces can be us
35b30 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ed to determine 
35b40 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74  the size.** of t
35b50 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
35b60 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ng..**.** ^If th
35b70 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
35b80 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
35b90 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
35ba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35bb0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
35bc0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
35bd0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
35be0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
35bf0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
35c00 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
35c10 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
35c20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35c30 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
35c40 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
35c50 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
35c60 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
35c70 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
35c80 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
35c90 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
35ca0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
35cb0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
35cc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
35cd0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
35ce0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
35cf0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
35d00 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
35d10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
35d20 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
35d30 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
35d40 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
35d50 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
35d60 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
35d70 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
35d80 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
35d90 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
35da0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
35db0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35dc0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
35dd0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
35de0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
35df0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
35e00 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
35e10 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
35e20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
35e30 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
35e40 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
35e50 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
35e60 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
35e70 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
35e80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
35e90 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
35ea0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
35eb0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
35ec0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35ed0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
35ee0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
35ef0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
35f00 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
35f10 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
35f20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
35f30 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
35f40 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
35f50 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
35f60 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
35f70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35f80 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
35f90 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
35fa0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
35fb0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
35fc0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
35fd0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
35fe0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
35ff0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
36000 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
36010 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
36020 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
36030 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
36040 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
36050 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
36060 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36070 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36080 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
36090 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
360a0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
360b0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
360c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
360d0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
360e0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
360f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
36100 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
36110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36120 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
36130 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
36140 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
36150 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
36160 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
36170 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
36180 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
36190 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
361a0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
361b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
361c0 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
361d0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
361e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
361f0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
36200 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
36210 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
36220 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
36230 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
36240 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
36250 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
36260 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
36270 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
36280 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
36290 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
362a0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
362b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
362c0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
362d0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
362e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
362f0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
36300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
36310 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
36320 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
36330 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
36340 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
36350 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
36360 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
36370 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36380 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
36390 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
363a0 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
363b0 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
363c0 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65  adsafe..** Hence
363d0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  , the sqlite3_co
363e0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74  lumn_value() int
363f0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72  erface.** is nor
36400 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75  mally only usefu
36410 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70  l within the imp
36420 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a  lementation of .
36430 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ** [application-
36440 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
36450 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75  tions] or [virtu
36460 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20  al tables], not 
36470 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65  within.** top-le
36480 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  vel application 
36490 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  code..**.** The 
364a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  these routines m
364b0 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  ay attempt to co
364c0 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74 79  nvert the dataty
364d0 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  pe of the result
364e0 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c  ..** ^For exampl
364f0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
36500 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
36510 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
36520 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
36530 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
36540 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
36550 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
36560 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
36570 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
36580 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
36590 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
365a0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
365b0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
365c0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
365d0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
365e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
365f0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
36600 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
36610 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
36620 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
36630 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
36640 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
36650 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
36660 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
36670 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
36680 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
36690 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
366a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
366b0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
366c0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
366d0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
366e0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
366f0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
36700 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
36710 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
36720 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
36730 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
36740 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
36750 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
36760 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
36770 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
36780 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
36790 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
367a0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
367b0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
367c0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
367d0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
367e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
367f0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
36800 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
36810 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
36820 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
36830 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
36840 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
36850 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
36860 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
36870 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
36880 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
36890 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
368a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
368b0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
368c0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
368d0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
368e0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
368f0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
36900 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
36910 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
36920 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
36930 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
36940 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
36950 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
36960 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
36970 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
36980 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
36990 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
369a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
369b0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
369c0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
369d0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
369e0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
369f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
36a00 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
36a10 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
36a20 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
36a30 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
36a40 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
36a50 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
36a60 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
36a70 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
36a80 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
36a90 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
36aa0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
36ab0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
36ac0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
36ad0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
36ae0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
36af0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
36b00 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
36b10 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
36b20 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
36b30 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
36b40 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
36b50 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
36b60 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
36b70 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
36b80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36b90 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
36ba0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
36bb0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
36bc0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
36bd0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
36be0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
36bf0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
36c00 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
36c10 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
36c20 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
36c30 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
36c40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
36c50 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
36c60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36c70 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
36c80 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
36c90 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
36ca0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
36cb0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
36cc0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
36cd0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
36ce0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
36cf0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
36d00 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
36d10 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
36d20 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
36d30 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
36d40 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
36d50 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
36d60 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
36d70 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
36d80 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
36d90 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
36da0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
36db0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
36dc0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
36dd0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
36de0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
36df0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
36e00 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
36e10 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
36e20 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
36e30 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
36e40 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
36e50 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
36e60 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
36e70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
36e80 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
36e90 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
36ea0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
36eb0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
36ec0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
36ed0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
36ee0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
36ef0 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
36f00 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
36f10 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
36f20 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
36f30 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
36f40 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
36f50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
36f60 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
36f70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36f80 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
36f90 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
36fa0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
36fb0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
36fc0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
36fd0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
36fe0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
36ff0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
37000 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
37010 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
37020 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
37030 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
37040 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
37050 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
37060 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
37070 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
37080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
37090 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
370a0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
370b0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
370c0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
370d0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
370e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
370f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
37100 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
37110 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
37120 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
37130 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
37140 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
37150 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
37160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
37170 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
37180 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
37190 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
371a0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
371b0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
371c0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
371d0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
371e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
371f0 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
37200 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
37210 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
37220 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
37230 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
37240 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
37250 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
37260 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
37270 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
37280 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
37290 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
372a0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
372b0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
372c0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
372d0 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
372e0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
372f0 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70  cally.  Do not p
37300 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
37310 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
37320 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
37330 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
37340 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
37350 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
37360 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
37370 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67  ]..**.** As long
37380 20 61 73 20 74 68 65 20 69 6e 70 75 74 20 70 61   as the input pa
37390 72 61 6d 65 74 65 72 73 20 61 72 65 20 63 6f 72  rameters are cor
373a0 72 65 63 74 2c 20 74 68 65 73 65 20 72 6f 75 74  rect, these rout
373b0 69 6e 65 73 20 77 69 6c 6c 20 6f 6e 6c 79 0a 2a  ines will only.*
373c0 2a 20 66 61 69 6c 20 69 66 20 61 6e 20 6f 75 74  * fail if an out
373d0 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72  -of-memory error
373e0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61   occurs during a
373f0 20 66 6f 72 6d 61 74 20 63 6f 6e 76 65 72 73 69   format conversi
37400 6f 6e 2e 0a 2a 2a 20 4f 6e 6c 79 20 74 68 65 20  on..** Only the 
37410 66 6f 6c 6c 6f 77 69 6e 67 20 73 75 62 73 65 74  following subset
37420 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 61   of interfaces a
37430 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 6f 75  re subject to ou
37440 74 2d 6f 66 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 65  t-of-memory.** e
37450 72 72 6f 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rrors:.**.** <ul
37460 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  >.** <li> sqlite
37470 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 0a  3_column_blob().
37480 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f  ** <li> sqlite3_
37490 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 0a 2a 2a  column_text().**
374a0 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f   <li> sqlite3_co
374b0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
374c0 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f   <li> sqlite3_co
374d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
374e0 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  <li> sqlite3_col
374f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
37500 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ul>.**.** If 
37510 61 6e 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  an out-of-memory
37520 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 74   error occurs, t
37530 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
37540 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 73 65 0a  alue from these.
37550 2a 2a 20 72 6f 75 74 69 6e 65 73 20 69 73 20 74  ** routines is t
37560 68 65 20 73 61 6d 65 20 61 73 20 69 66 20 74 68  he same as if th
37570 65 20 63 6f 6c 75 6d 6e 20 68 61 64 20 63 6f 6e  e column had con
37580 74 61 69 6e 65 64 20 61 6e 20 53 51 4c 20 4e 55  tained an SQL NU
37590 4c 4c 20 76 61 6c 75 65 2e 0a 2a 2a 20 56 61 6c  LL value..** Val
375a0 69 64 20 53 51 4c 20 4e 55 4c 4c 20 72 65 74 75  id SQL NULL retu
375b0 72 6e 73 20 63 61 6e 20 62 65 20 64 69 73 74 69  rns can be disti
375c0 6e 67 75 69 73 68 65 64 20 66 72 6f 6d 20 6f 75  nguished from ou
375d0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f  t-of-memory erro
375e0 72 73 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e  rs.** by invokin
375f0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  g the [sqlite3_e
37600 72 72 63 6f 64 65 28 29 5d 20 69 6d 6d 65 64 69  rrcode()] immedi
37610 61 74 65 6c 79 20 61 66 74 65 72 20 74 68 65 20  ately after the 
37620 73 75 73 70 65 63 74 0a 2a 2a 20 72 65 74 75 72  suspect.** retur
37630 6e 20 76 61 6c 75 65 20 69 73 20 6f 62 74 61 69  n value is obtai
37640 6e 65 64 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ned and before a
37650 6e 79 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ny.** other SQLi
37660 74 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  te interface is 
37670 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 73 61  called on the sa
37680 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
37690 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 63 6f 6e  nection]..*/.con
376a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
376b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
376c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
376d0 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
376e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
376f0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
37700 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
37710 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
37720 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
37730 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
37740 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
37750 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
37760 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
37770 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
37780 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
37790 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
377a0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
377b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
377c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
377d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
377e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
377f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
37800 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
37810 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
37820 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
37830 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
37840 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37850 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
37860 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
37870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37880 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
37890 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
378a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
378b0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
378c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
378d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
378e0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
378f0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
37900 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52   Object.** DESTR
37910 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
37920 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
37930 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
37940 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
37950 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
37960 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
37970 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
37980 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
37990 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
379a0 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
379b0 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
379c0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
379d0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
379e0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
379f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
37a00 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
37a10 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
37a20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
37a30 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
37a40 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
37a50 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
37a60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
37a70 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
37a80 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
37a90 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
37aa0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
37ab0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
37ac0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
37ad0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
37ae0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
37af0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
37b00 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
37b10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
37b20 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
37b30 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
37b40 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
37b50 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
37b60 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
37b70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
37b80 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
37b90 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
37ba0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
37bb0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
37bc0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
37bd0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
37be0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
37bf0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
37c00 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
37c10 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
37c20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
37c30 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
37c40 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
37c50 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
37c60 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
37c70 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
37c80 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
37c90 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
37ca0 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
37cb0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
37cc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
37cd0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
37ce0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37cf0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
37d00 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
37d10 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
37d20 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
37d30 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
37d40 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
37d50 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
37d60 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
37d70 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
37d80 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
37d90 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
37da0 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
37db0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
37dc0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
37dd0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
37de0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
37df0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
37e00 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d  ment Object.** M
37e10 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
37e20 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  tmt.**.** The sq
37e30 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
37e40 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
37e50 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
37e60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37e70 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
37e80 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
37e90 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
37ea0 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
37eb0 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
37ec0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
37ed0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
37ee0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
37ef0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
37f00 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
37f10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
37f20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
37f30 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
37f40 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
37f50 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
37f60 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
37f70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
37f80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
37f90 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
37fa0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
37fb0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
37fc0 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
37fd0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
37fe0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
37ff0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
38000 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
38010 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
38020 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
38030 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
38040 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
38050 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
38060 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
38070 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
38080 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
38090 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
380a0 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
380b0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
380c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
380d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
380e0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
380f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
38100 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
38110 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
38120 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
38130 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
38140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
38150 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
38160 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
38170 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
38180 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
38190 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
381a0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
381b0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
381c0 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
381d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
381e0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
381f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
38200 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
38210 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
38220 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
38230 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38240 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
38250 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
38260 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
38270 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
38280 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
38290 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
382a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
382b0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
382c0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
382d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
382e0 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  L functions}.** 
382f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
38300 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
38310 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
38320 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
38330 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
38340 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
38350 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
38360 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
38370 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
38380 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
38390 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
383a0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
383b0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
383c0 73 2e 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  s. The only diff
383d0 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
383e0 2a 2a 20 74 68 65 20 74 68 72 65 65 20 22 73 71  ** the three "sq
383f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
38400 63 74 69 6f 6e 2a 22 20 72 6f 75 74 69 6e 65 73  ction*" routines
38410 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e   are the text en
38420 63 6f 64 69 6e 67 20 0a 2a 2a 20 65 78 70 65 63  coding .** expec
38430 74 65 64 20 66 6f 72 20 74 68 65 20 73 65 63 6f  ted for the seco
38440 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
38450 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
38460 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 0a 2a 2a  nction being .**
38470 20 63 72 65 61 74 65 64 29 20 61 6e 64 20 74 68   created) and th
38480 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
38490 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
384a0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
384b0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
384c0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
384d0 65 72 2e 20 46 75 6e 63 74 69 6f 6e 20 73 71 6c  er. Function sql
384e0 69 74 65 33 5f 63 72 65 61 74 65 5f 77 69 6e 64  ite3_create_wind
384f0 6f 77 5f 66 75 6e 63 74 69 6f 6e 28 29 0a 2a 2a  ow_function().**
38500 20 69 73 20 73 69 6d 69 6c 61 72 2c 20 62 75 74   is similar, but
38510 20 61 6c 6c 6f 77 73 20 74 68 65 20 75 73 65 72   allows the user
38520 20 74 6f 20 73 75 70 70 6c 79 20 74 68 65 20 65   to supply the e
38530 78 74 72 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  xtra callback fu
38540 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6e 65 65 64 65  nctions.** neede
38550 64 20 62 79 20 5b 61 67 67 72 65 67 61 74 65 20  d by [aggregate 
38560 77 69 6e 64 6f 77 20 66 75 6e 63 74 69 6f 6e 73  window functions
38570 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  ]..**.** ^The fi
38580 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
38590 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
385a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
385b0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
385c0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
385d0 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
385e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
385f0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
38600 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
38610 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
38620 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
38630 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
38640 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
38650 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
38660 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
38670 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
38680 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
38690 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
386a0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
386b0 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
386c0 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
386d0 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
386e0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
386f0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
38700 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
38710 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
38720 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
38730 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
38740 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
38750 65 20 6e 61