/ Hex Artifact Content
Login

Artifact d831ecb386de7a5e67caca0edc73570dd8c9f140550520ba170dad121d1a2a34:


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 6c 73 65 0a 23 20 64  nt N);.#else.# d
1e00: 65 66 69 6e 65 20 73 71 6c 69 74 65 33 5f 63 6f  efine sqlite3_co
1e10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1e20: 28 58 29 20 30 0a 23 20 64 65 66 69 6e 65 20 73  (X) 0.# define s
1e30: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1e40: 74 69 6f 6e 5f 67 65 74 28 58 29 20 20 28 28 76  tion_get(X)  ((v
1e50: 6f 69 64 2a 29 30 29 0a 23 65 6e 64 69 66 0a 0a  oid*)0).#endif..
1e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e70: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1e80: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1e90: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1eb0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ec0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1ed0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1ee0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1ef0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1f00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1f10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1f20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1f40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1f50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1f60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1f70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1f80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1f90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1fa0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1fb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1fc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1fd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1fe0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1ff0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
2000: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
2010: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2020: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
2030: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
2040: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
2050: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
2060: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
2070: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
2080: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
2090: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
20a0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
20b0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
20c0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
20d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
20e0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
20f0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
2100: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
2110: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
2120: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
2130: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
2140: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
2150: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
2160: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
2170: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
2180: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
2190: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
21a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
21b0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
21c0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
21d0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
21e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
21f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
2200: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
2210: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
2220: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2230: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
2240: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
2250: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2260: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
2270: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
2280: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
2290: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
22a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
22b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
22c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
22d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
22e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
22f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2300: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2310: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2320: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2330: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2340: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2350: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2360: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2370: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2380: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2390: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
23a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
23b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
23c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
23d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
23e0: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72  LIZED].  ^(The r
23f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2400: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
2410: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
2420: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
2430: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2440: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
2450: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
2460: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
2470: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
2480: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
2490: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
24a0: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
24b0: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
24c0: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
24d0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
24e0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
24f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2500: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
2510: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
2520: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
2530: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2550: 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ation..*/.int sq
2560: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2570: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
2580: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2590: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
25a0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
25b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
25c0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
25d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
25e0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
25f0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2600: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2610: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2620: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2630: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
2640: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
2650: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
2660: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
2670: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
2680: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
2690: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
26a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
26b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
26c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
26d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
26e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
26f0: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2700: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2710: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2720: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2730: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
2740: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2750: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
2760: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
2770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2790: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27a0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
27b0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
27c0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
27d0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
27e0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
27f0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2800: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2810: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2820: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2830: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
2840: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
2850: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
2860: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
2870: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
2880: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
2890: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
28a0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
28b0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
28c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
28d0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
28e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
28f0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2900: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2920: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2930: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
2940: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
2950: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
2960: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
2970: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2980: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
2990: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
29a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
29b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
29c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
29d0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
29e0: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
29f0: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2a00: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2a10: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2a20: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2a30: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
2a40: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2a50: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
2a60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2a70: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2a80: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
2a90: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2aa0: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2ab0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2ac0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2ad0: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2ae0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2af0: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2b00: 34 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54  4;.# ifdef SQLIT
2b10: 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  E_UINT64_TYPE.  
2b20: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2b30: 5f 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  _UINT64_TYPE sql
2b40: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c  ite_uint64;.# el
2b50: 73 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66  se  .    typedef
2b60: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2b70: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2b80: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64  te_uint64;.# end
2b90: 69 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  if.#elif defined
2ba0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
2bb0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
2bc0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
2bd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2be0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2bf0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2c00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2c10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2c20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2c30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2c50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2c60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2c70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2c80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2c90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2ca0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2cb0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2cc0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2cd0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2ce0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2cf0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2d00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2d10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2d20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2d30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2d40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2d50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2d60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2d70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2d80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2d90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2da0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
2db0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
2dc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2dd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2de0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
2df0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
2e00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
2e10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2e20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2e30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2e40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2e50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
2e60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
2e70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2e80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
2e90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
2ea0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
2eb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
2ec0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ed0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
2ee0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ef0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
2f00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2f10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
2f20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
2f30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2f40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
2f50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
2f60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
2f70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
2f90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
2fa0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
2fb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2fc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
2fd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2fe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2ff0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
3000: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
3010: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
3020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3030: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
3040: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
3050: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
3060: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
3070: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
3080: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
3090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30a0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
30b0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
30c0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
30d0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
30e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
30f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
3100: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
3110: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
3120: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
3130: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
3140: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
3150: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
3160: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
3170: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
3180: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
3190: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
31a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31b0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
31c0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
31d0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
31e0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
31f0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
3200: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3210: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
3220: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
3230: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3240: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3250: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3260: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3280: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3290: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
32a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
32c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
32d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
32f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3300: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3310: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3320: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3340: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3350: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
3360: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
3370: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3380: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3390: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
33a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
33b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
33c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
33d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
33e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
33f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3400: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3410: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3420: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3440: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3450: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3460: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3470: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3480: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
34a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
34c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
34d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
34e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
34f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3500: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3510: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3520: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3530: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3540: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3550: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3560: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3570: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3580: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3590: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
35a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
35b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
35c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
35d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
35e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
35f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
3600: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
3610: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3620: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3630: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3640: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3650: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3660: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3670: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3680: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3690: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
36a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
36b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
36c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
36d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
36e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
3700: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
3710: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3720: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3730: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3740: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3750: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3760: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3790: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
37a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
37c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
37d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
37e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
37f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3800: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3810: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3820: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3830: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3840: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3850: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3860: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3870: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3880: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3890: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
38a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
38b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
38c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
38e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
38f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3900: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3910: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3920: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3930: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3940: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3950: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3960: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3970: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3980: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3990: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
39a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
39b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
39c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
39d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
39e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
39f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3a00: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3a10: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3a30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3a40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3a50: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3a60: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3a70: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3a80: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3a90: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3aa0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3ab0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
3ac0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3ad0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3ae0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3af0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3b00: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3b10: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3b20: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3b30: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3b40: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3b50: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3b60: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3b70: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3b80: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3b90: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3ba0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3bb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3bc0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3bd0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3be0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3bf0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3c00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3c10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3c20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3c30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3c40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3c50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3c60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3c70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3c80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3c90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3ca0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3cb0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3cc0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3cd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3cf0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3d00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3d10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3d20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3d30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3d40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3d50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3d60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3d70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3d80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3d90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3da0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3db0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3dc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3dd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3de0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3df0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3e00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3e10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3e20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3e30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3e40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3e50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3e70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3e80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3e90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3ea0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3eb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3ec0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3ed0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ee0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3ef0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3f00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3f10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3f20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3f30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3f40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3f50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3f60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3f70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3f80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fa0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3fb0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3fc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3fd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3fe0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ff0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
4000: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
4010: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
4020: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
4030: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
4040: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
4050: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
4060: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
4070: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
4080: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
4090: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
40a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40b0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
40c0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
40d0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
40e0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
40f0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
4100: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
4110: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
4120: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
4130: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
4140: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
4150: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
4160: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
4170: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
4180: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
4190: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
41a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
41b0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
41c0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
41d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
41e0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
41f0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
4200: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4210: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4220: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4230: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4250: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4260: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4270: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4280: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4290: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
42a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
42b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
42c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
42d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
42e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
42f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
4300: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
4310: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4320: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4330: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4340: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4350: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
4360: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4370: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4390: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
43a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
43b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
43e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
43f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4410: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4420: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4430: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4460: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4470: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4480: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4490: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
44a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
44c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
44d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
44e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
44f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4510: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4520: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4530: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4540: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4550: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4560: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4570: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4580: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4590: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
45a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
45b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
45c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
45d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
45e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
45f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4600: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4620: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4630: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4640: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4650: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4670: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4680: 20 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f   /* Generic erro
4690: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
46a0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
46b0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
46c0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
46d0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
46f0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4700: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4710: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4720: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4730: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4740: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4750: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4770: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4780: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4790: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
47a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47b0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
47c0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
47d0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
47e0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4800: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4810: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4820: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4830: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4840: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4850: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4860: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4880: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4890: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
48a0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
48b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
48c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48d0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
48e0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
48f0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4900: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4920: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4930: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4940: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4950: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4960: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4970: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4980: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
4990: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
49a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
49b0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
49c0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
49d0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
49e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
49f0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4a00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4a10: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4a20: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4a30: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4a50: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4a60: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4a70: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4a90: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4aa0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20  /* Internal use 
4ab0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
4ac0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4ad0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4ae0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4af0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4b00: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4b10: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4b20: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4b30: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4b40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4b60: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4b70: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4b80: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4b90: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4ba0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4bb0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4bc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4bd0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4be0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4bf0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4c00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c10: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4c20: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4c30: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4c40: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4c50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4c60: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4c70: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4c80: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4c90: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4ca0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74       24   /* Not
4cb0: 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
4cc0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
4cd0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
4ce0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
4cf0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
4d00: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
4d10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
4d20: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
4d30: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
4d40: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
4d50: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4d60: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20  SQLITE_NOTICE   
4d70: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66     27   /* Notif
4d80: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71  ications from sq
4d90: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
4db0: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f  RNING     28   /
4dc0: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20  * Warnings from 
4dd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4df0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
4e00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4e10: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
4e20: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
4e30: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
4e40: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
4e50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4e60: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
4e70: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
4e80: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4e90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4ea0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
4eb0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4ec0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
4ee0: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e  itions}.**.** In
4ef0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4f00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4f10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4f20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30  return one of 30
4f30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73   integer.** [res
4f40: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4f50: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4f60: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4f70: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4f80: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4f90: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4fa0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4fb0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4fc0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4fd0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4fe0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4ff0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
5000: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
5010: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
5020: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
5030: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
5040: 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e  3.3.8 [dateof:3.
5050: 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65  3.8].** and late
5060: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
5070: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
5080: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
5090: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
50a0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
50b0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
50c0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
50d0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
50e0: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
50f0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
5100: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
5110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
5120: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
5130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
5140: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
5150: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
5160: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
5170: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
5180: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
5190: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
51a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
51b0: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
51c0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
51d0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53  SQLITE_ERROR_MIS
51e0: 53 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28  SING_COLLSEQ   (
51f0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28  SQLITE_ERROR | (
5200: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5210: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52  QLITE_ERROR_RETR
5220: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  Y             (S
5230: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32  QLITE_ERROR | (2
5240: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5250: 4c 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53  LITE_ERROR_SNAPS
5260: 48 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51  HOT          (SQ
5270: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c  LITE_ERROR | (3<
5280: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5290: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
52a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
52c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
52d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
52e0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
52f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5300: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5310: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5320: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5330: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5350: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5370: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
53a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
53c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
53d0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
53e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
53f0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5410: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5420: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5430: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5450: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5460: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5470: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5490: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
54a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54b0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
55e0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
55f0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56d0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56f0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5710: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5720: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5730: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5750: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5760: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5770: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5780: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5790: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
57a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57b0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
57c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57d0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
57e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57f0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5810: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5820: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5830: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5840: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5850: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5860: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5870: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5890: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
58a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58b0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58d0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58f0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5910: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5920: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5930: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5950: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5960: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5970: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5990: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59b0: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
59d0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59f0: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5a10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5a30: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a50: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a70: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5a90: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  ED_VTAB         
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5ab0: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64  ED |  (2<<8)).#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ad0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5af0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5b10: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5b30: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5b40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b50: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5b60: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5b70: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5bc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5be0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5bf0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5c20: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5c30: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5c40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5c60: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28  DIRTYWAL       (
5c70: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5c80: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74  | (5<<8)) /* Not
5c90: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   Used */.#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5cb0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5ce0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5cf0: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20  _SEQUENCE       
5d00: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5d10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5d20: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5d30: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5d40: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5d50: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5d70: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5d80: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5d90: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5db0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
5dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5dd0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
5de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5df0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5e00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e10: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5e20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e30: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49  E_READONLY_CANTI
5e40: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54  NIT       (SQLIT
5e50: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c  E_READONLY | (5<
5e60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e70: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52  ITE_READONLY_DIR
5e80: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c  ECTORY      (SQL
5e90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5ea0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5eb0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5ec0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5ed0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5ee0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ef0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5f00: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5f10: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5f30: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5f40: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5f50: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5f60: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5f80: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5f90: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5fa0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5fc0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5fd0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5ff0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6000: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6010: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
6020: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6030: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
6040: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6050: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
6060: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6070: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6090: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
60a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
60b0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
60c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
60d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
60e0: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
60f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
6100: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6110: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6120: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
6130: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6140: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
6150: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6160: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
6170: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6180: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61a0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
61b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
61c0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61e0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
61f0: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
6200: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6220: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
6230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
6240: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
6260: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
6270: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
6280: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
62a0: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
62b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
62c0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
62d0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
62e0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
62f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
6300: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
6310: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6320: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6330: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
6340: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
6350: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
6360: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
6370: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
6380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6390: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
63a0: 0a 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 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
63d0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* 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 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6410: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6420: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6430: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6450: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
6460: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6470: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
6480: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
64b0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
64c0: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
64f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6500: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6520: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6530: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
6540: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
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 55 52 49 20 20 20 20 20  TE_OPEN_URI     
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
6590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65b0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
65c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
65d0: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
65e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6610: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6620: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6640: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6660: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
6670: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6680: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
6690: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
66a0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
66b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
66d0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
66e0: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
66f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6700: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6710: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6720: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6740: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6750: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
6760: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6770: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6780: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6790: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
67a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
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 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
67d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
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 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6820: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
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 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
6870: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
6880: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6890: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
68b0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
68c0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
68d0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
68e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6900: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6910: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6920: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6930: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6940: 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54  TE_OPEN_FILEPROT
6950: 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20  ECTION_MASK     
6960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6970: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6980: 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72  700000../* Reser
6990: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
69a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
69b0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
69c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
69d0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
69e0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
69f0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6a00: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6a10: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6a20: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6a30: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6a40: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6a50: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6a60: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6a70: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6a80: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6a90: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6aa0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6ab0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6ac0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6ad0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6ae0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
6af0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6b00: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6b10: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6b20: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6b30: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6b40: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6b50: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6b60: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6b70: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6b80: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6b90: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6ba0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6bb0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6bc0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6bd0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6be0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
6bf0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6c00: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6c10: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6c20: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6c30: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6c40: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6c50: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6c60: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6c70: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6c80: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6c90: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6ca0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6cb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6cc0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6cd0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6ce0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
6cf0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6d00: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6d10: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6d20: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6d30: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6d40: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6d50: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6d60: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6d70: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6d80: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6d90: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6da0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6db0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6dc0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6dd0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6de0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
6df0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6e00: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6e10: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6e20: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6e30: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6e40: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6e50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6e60: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6e70: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6e80: 69 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69  icates that a fi
6e90: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6ea0: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6eb0: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6ec0: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6ed0: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6ee0: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6ef0: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6f00: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
6f10: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
6f20: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
6f30: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
6f40: 69 76 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20  ivileges..**.** 
6f50: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6f60: 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 70 72  _BATCH_ATOMIC pr
6f70: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6f80: 74 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  t the underlying
6f90: 0a 2a 2a 20 66 69 6c 65 73 79 73 74 65 6d 20 73  .** filesystem s
6fa0: 75 70 70 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75  upports doing mu
6fb0: 6c 74 69 70 6c 65 20 77 72 69 74 65 20 6f 70 65  ltiple write ope
6fc0: 72 61 74 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c  rations atomical
6fd0: 6c 79 20 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a  ly when those.**
6fe0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
6ff0: 73 20 61 72 65 20 62 72 61 63 6b 65 74 65 64 20  s are bracketed 
7000: 62 79 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  by [SQLITE_FCNTL
7010: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
7020: 49 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c  ITE] and.** [SQL
7030: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
7040: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a  _ATOMIC_WRITE]..
7050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7060: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
7070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7080: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
7090: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
70a0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
70b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
70c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
70d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
70e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
70f0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
7100: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7110: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
7120: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
7130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7140: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
7150: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7160: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
7170: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7180: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
7190: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
71a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
71b0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
71c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
71d0: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
71e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
71f0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
7200: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
7210: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7220: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
7230: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
7240: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7250: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
7260: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
7270: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
7280: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
7290: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
72a0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
72b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
72c0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
72d0: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
72e0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
72f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
7300: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
7310: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
7320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7330: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
7340: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7350: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
7360: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
7370: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
7380: 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a   0x00004000../*.
7390: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
73a0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
73b0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
73c0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
73d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
73e0: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
73f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
7400: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
7410: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
7420: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
7430: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
7440: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7450: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
7460: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
7470: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
7480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7490: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
74a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
74b0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
74c0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
74d0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
74e0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
74f0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
7500: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
7510: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
7520: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
7530: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
7540: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
7550: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
7560: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
7570: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7580: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
7590: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
75a0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
75b0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
75c0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
75d0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
75e0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
75f0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
7600: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
7610: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
7620: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
7630: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
7640: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
7650: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
7660: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
7670: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
7680: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
7690: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
76a0: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
76b0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
76c0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
76d0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
76e0: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
76f0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
7700: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
7710: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
7720: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
7730: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
7740: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
7750: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
7760: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
7770: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
7780: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7790: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
77a0: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
77b0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
77c0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
77d0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
77e0: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
77f0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
7800: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
7810: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
7820: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
7830: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
7840: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
7850: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
7860: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
7870: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
7880: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7890: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
78a0: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
78b0: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
78c0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
78d0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
78e0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
78f0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
7900: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
7910: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
7920: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
7930: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
7940: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
7950: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
7960: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
7970: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
7980: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
7990: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
79a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
79b0: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
79c0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
79d0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
79e0: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
79f0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
7a00: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
7a10: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
7a20: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7a30: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
7a40: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
7a50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7a60: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
7a70: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
7a80: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7a90: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
7aa0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
7ab0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7ac0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
7ad0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
7ae0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7af0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
7b00: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
7b10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
7b20: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
7b30: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
7b40: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
7b50: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
7b60: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
7b70: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
7b80: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
7b90: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
7ba0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
7bb0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
7bc0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
7bd0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
7be0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
7bf0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
7c00: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
7c10: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
7c20: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
7c30: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
7c40: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
7c50: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7c60: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
7c70: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
7c80: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
7c90: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
7ca0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7cb0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
7cc0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
7cd0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
7ce0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7cf0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
7d00: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
7d10: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
7d20: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
7d30: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7d40: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7d50: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
7d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7d70: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
7d80: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
7d90: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
7da0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7db0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
7dc0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
7dd0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
7de0: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
7df0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
7e00: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
7e10: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
7e20: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
7e30: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
7e40: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
7e50: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7e60: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
7e70: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
7e80: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7e90: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
7ea0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7eb0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
7ec0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
7ed0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
7ee0: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
7ef0: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
7f00: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
7f10: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
7f20: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7f30: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
7f40: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
7f50: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
7f60: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
7f70: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
7f80: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
7f90: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7fa0: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
7fb0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7fc0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
7fd0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7fe0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
7ff0: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
8000: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8010: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
8020: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
8030: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
8040: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
8050: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
8060: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
8070: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
8080: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
8090: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
80a0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
80b0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
80c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
80d0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
80e0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
80f0: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
8100: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
8110: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
8120: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
8130: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
8140: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
8150: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
8160: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
8170: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
8180: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8190: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
81a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
81b0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
81c0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
81d0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
81e0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
81f0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
8200: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
8210: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
8220: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
8230: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
8240: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
8250: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
8260: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
8270: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
8280: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
8290: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
82a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
82b0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
82c0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
82d0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
82e0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
82f0: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
8300: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
8310: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
8320: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
8330: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
8340: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
8350: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
8360: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
8370: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
8380: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
8390: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
83a0: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
83b0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
83c0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
83d0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
83e0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
83f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
8400: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
8410: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
8420: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
8430: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
8440: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
8450: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
8460: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
8470: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
8480: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
8490: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
84a0: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
84b0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
84c0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
84d0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
84e0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
84f0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
8500: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
8510: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
8520: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
8530: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
8540: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
8550: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
8560: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
8570: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
8580: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
8590: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
85a0: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
85b0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
85c0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
85d0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
85e0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
85f0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
8600: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
8610: 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74  .** A [file cont
8620: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69  rol opcodes | li
8630: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
8640: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
8650: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
8660: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
8670: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
8680: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8690: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
86a0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
86b0: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
86c0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
86d0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
86e0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
86f0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
8700: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
8710: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
8720: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
8730: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
8740: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
8750: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
8760: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
8770: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
8780: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
8790: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
87a0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
87b0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
87c0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
87d0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
87e0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
87f0: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
8800: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
8810: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
8820: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
8830: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
8840: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
8850: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
8860: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
8870: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
8880: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8890: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
88a0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
88b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
88c0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
88d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
88e0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
88f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8900: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
8910: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8920: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
8930: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8940: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
8950: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8960: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
8970: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8980: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
8990: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
89a0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
89b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
89c0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
89d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
89e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
89f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8a00: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
8a10: 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c  _WHEN_OPEN].** <
8a20: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8a30: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
8a40: 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  WRITE].** <li> [
8a50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
8a60: 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  UTABLE].** <li> 
8a70: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41  [SQLITE_IOCAP_BA
8a80: 54 43 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  TCH_ATOMIC].** <
8a90: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
8aa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8ab0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
8ac0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
8ad0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
8ae0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
8b00: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
8b10: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
8b20: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
8b30: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
8b40: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
8b50: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
8b60: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
8b70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
8b80: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
8b90: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8ba0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8bb0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
8bc0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
8bd0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
8be0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
8bf0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
8c00: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
8c10: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
8c20: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
8c30: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
8c40: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
8c50: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
8c60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8c70: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8c80: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
8c90: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
8ca0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
8cb0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
8cc0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
8cd0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
8ce0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
8cf0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
8d00: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
8d10: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
8d20: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
8d30: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
8d40: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
8d50: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
8d60: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8d70: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
8d80: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
8d90: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
8da0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8db0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
8dc0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
8dd0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
8de0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
8df0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
8e00: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
8e10: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8e20: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
8e30: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
8e40: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
8e50: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
8e60: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8e70: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
8e80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
8e90: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8ea0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8eb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
8ec0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8ed0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
8ee0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8ef0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8f00: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8f10: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8f30: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8f40: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8f50: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
8f60: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
8f70: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8f80: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8f90: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
8fa0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
8fb0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8fc0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
8fd0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8fe0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
8ff0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
9000: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
9010: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
9020: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
9030: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
9040: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
9050: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
9060: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
9070: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
9080: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
9090: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
90a0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
90b0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
90c0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
90d0: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
90e0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
90f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
9100: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
9110: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
9120: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
9130: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
9140: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
9150: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
9160: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
9170: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
9180: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
9190: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
91a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
91b0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
91c0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
91d0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
91e0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74  rsion 2 */.  int
91f0: 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74   (*xFetch)(sqlit
9200: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
9210: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69  3_int64 iOfst, i
9220: 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a  nt iAmt, void **
9230: 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  pp);.  int (*xUn
9240: 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  fetch)(sqlite3_f
9250: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9260: 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20  t64 iOfst, void 
9270: 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  *p);.  /* Method
9280: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
9290: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  d for version 3 
92a0: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  */.  /* Addition
92b0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
92c0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
92d0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
92e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
92f0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
9300: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
9310: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69  ** KEYWORDS: {fi
9320: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
9330: 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f  es} {file contro
9340: 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  l opcode}.**.** 
9350: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
9360: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
9370: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
9380: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
9390: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
93a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
93b0: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
93c0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
93d0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
93e0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c  terface..**.** <
93f0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  ul>.** <li>[[SQL
9400: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
9410: 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ATE]].** The [SQ
9420: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
9430: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
9440: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
9450: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
9460: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
9470: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
9480: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
9490: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
94a0: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
94b0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
94c0: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
94d0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
94e0: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
94f0: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
9500: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
9510: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
9520: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
9530: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
9540: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
9550: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
9560: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
9570: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
9580: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
9590: 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
95a0: 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54  e when the SQLIT
95b0: 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c  E_TEST.** compil
95c0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
95d0: 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   used..**.** <li
95e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
95f0: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
9600: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9610: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
9620: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
9630: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
9640: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
9650: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
9660: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
9670: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
9680: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
9690: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
96a0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
96b0: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
96c0: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
96d0: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
96e0: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
96f0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
9700: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
9710: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
9720: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
9730: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
9740: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
9750: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
9760: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9770: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
9780: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
9790: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
97a0: 5f 4c 49 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20  _LIMIT]].** The 
97b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
97c0: 5a 45 5f 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65  ZE_LIMIT] opcode
97d0: 20 69 73 20 75 73 65 64 20 62 79 20 69 6e 2d 6d   is used by in-m
97e0: 65 6d 6f 72 79 20 56 46 53 20 74 68 61 74 0a 2a  emory VFS that.*
97f0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71  * implements [sq
9800: 6c 69 74 65 33 5f 64 65 73 65 72 69 61 6c 69 7a  lite3_deserializ
9810: 65 28 29 5d 20 74 6f 20 73 65 74 20 61 6e 20 75  e()] to set an u
9820: 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68  pper bound on th
9830: 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65  e size.** of the
9840: 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
9850: 61 73 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ase.  The argume
9860: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
9870: 74 6f 20 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e  to a [sqlite3_in
9880: 74 36 34 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  t64]..** If the 
9890: 69 6e 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20  integer pointed 
98a0: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
98b0: 74 68 65 6e 20 69 74 20 69 73 20 66 69 6c 6c 65  then it is fille
98c0: 64 20 69 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  d in with the.**
98d0: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20   current limit. 
98e0: 20 4f 74 68 65 72 77 69 73 65 20 74 68 65 20 6c   Otherwise the l
98f0: 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 74  imit is set to t
9900: 68 65 20 6c 61 72 67 65 72 20 6f 66 20 74 68 65  he larger of the
9910: 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
9920: 20 69 6e 74 65 67 65 72 20 70 6f 69 6e 74 65 64   integer pointed
9930: 20 74 6f 20 61 6e 64 20 74 68 65 20 63 75 72 72   to and the curr
9940: 65 6e 74 20 64 61 74 61 62 61 73 65 20 73 69 7a  ent database siz
9950: 65 2e 20 20 54 68 65 20 69 6e 74 65 67 65 72 0a  e.  The integer.
9960: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73  ** pointed to is
9970: 20 73 65 74 20 74 6f 20 74 68 65 20 6e 65 77 20   set to the new 
9980: 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  limit..**.** <li
9990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
99a0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
99b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
99c0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
99d0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
99e0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
99f0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
9a00: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
9a10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9a20: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
9a30: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
9a40: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
9a50: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
9a60: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
9a70: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
9a80: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
9a90: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
9aa0: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
9ab0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
9ac0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
9ad0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
9ae0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
9af0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
9b00: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
9b10: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
9b20: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
9b30: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
9b40: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
9b50: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
9b60: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
9b70: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
9b80: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
9b90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9ba0: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
9bb0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9bc0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
9bd0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9be0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9bf0: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9c00: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9c10: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9c20: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
9c30: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9c40: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
9c50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9c60: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e  OURNAL_POINTER].
9c70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9c80: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9c90: 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  L_POINTER]].** T
9ca0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9cb0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
9cc0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9cd0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
9ce0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
9cf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9d00: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
9d10: 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c  with the journal
9d20: 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a   file (either.**
9d30: 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a   the [rollback j
9d40: 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b  ournal] or the [
9d50: 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d  write-ahead log]
9d60: 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ) for a particul
9d70: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9d80: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9d90: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
9da0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9db0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9dc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9dd0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9de0: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9df0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9e00: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9e10: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9e20: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9e30: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9e40: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9e50: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
9e60: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
9e70: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
9e80: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
9e90: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
9ea0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
9eb0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
9ec0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9ed0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9ee0: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9ef0: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9f00: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9f10: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9f20: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9f30: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
9f40: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
9f50: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
9f60: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9f70: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
9f80: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
9f90: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
9fa0: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
9fb0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
9fc0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
9fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9fe0: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9ff0: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
a000: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
a010: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
a020: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
a030: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
a040: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
a050: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
a060: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
a070: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
a080: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
a090: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
a0a0: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
a0b0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
a0c0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
a0d0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
a0e0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
a0f0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a100: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
a110: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
a120: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
a130: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
a140: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
a150: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
a160: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
a170: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a180: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
a190: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
a1a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
a1b0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
a1c0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
a1d0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
a1e0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
a1f0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
a200: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
a210: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
a220: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
a230: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
a240: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
a250: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
a260: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
a270: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
a280: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
a290: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
a2a0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
a2b0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
a2c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a2d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
a2e0: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
a2f0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
a300: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
a310: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
a320: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
a330: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
a340: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
a350: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a360: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
a370: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a380: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
a390: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
a3a0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
a3b0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
a3c0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
a3d0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
a3e0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
a3f0: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
a400: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
a410: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
a420: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
a430: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
a440: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
a450: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
a460: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
a470: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
a480: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
a490: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
a4a0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
a4b0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
a4c0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
a4d0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
a4e0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
a4f0: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
a500: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
a510: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
a520: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
a530: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
a540: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
a550: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
a560: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
a570: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
a580: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
a590: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
a5a0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
a5b0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
a5c0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
a5d0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
a5e0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
a5f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
a600: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
a610: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
a620: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
a630: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
a640: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
a650: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
a660: 73 74 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  st integer is th
a670: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
a680: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
a690: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
a6a0: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
a6b0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
a6c0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
a6d0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
a6e0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
a6f0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
a700: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
a710: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
a720: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
a730: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
a740: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
a750: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
a760: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
a770: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
a780: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
a790: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
a7a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a7b0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
a7c0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a7d0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a7e0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
a7f0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
a800: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
a810: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
a820: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
a830: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
a840: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
a850: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
a860: 20 6c 6f 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d   log ([WAL file]
a870: 29 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  ) and shared mem
a880: 6f 72 79 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65  ory.** files use
a890: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
a8a0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
a8b0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
a8c0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
a8d0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
a8e0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
a8f0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
a900: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
a910: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
a920: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
a930: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
a940: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
a950: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
a960: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
a970: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
a980: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
a990: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
a9a0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a9b0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a9c0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a9d0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a9e0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a9f0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
aa00: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
aa10: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
aa20: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
aa30: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
aa40: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
aa50: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
aa60: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
aa70: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
aa80: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
aa90: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
aaa0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
aab0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
aac0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
aad0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
aae0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
aaf0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
ab00: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
ab10: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
ab20: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
ab30: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
ab40: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
ab50: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
ab60: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
ab70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab80: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
ab90: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
aba0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
abb0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
abc0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
abd0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
abe0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
abf0: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
ac00: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
ac10: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
ac20: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
ac30: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
ac40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
ac50: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
ac60: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
ac70: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
ac80: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
ac90: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
aca0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
acb0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
acc0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
acd0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
ace0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
acf0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
ad00: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
ad10: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
ad20: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
ad30: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
ad40: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
ad50: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
ad60: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
ad70: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
ad80: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
ad90: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
ada0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
adb0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
adc0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
add0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ade0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
adf0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
ae00: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
ae10: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
ae20: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
ae30: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
ae40: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
ae50: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
ae60: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
ae70: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
ae80: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
ae90: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
aea0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
aeb0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
aec0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
aed0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
aee0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
aef0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
af00: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
af10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
af20: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
af30: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
af40: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
af50: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
af60: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
af70: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
af80: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
af90: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
afa0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
afb0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
afc0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
afd0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
afe0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
aff0: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
b000: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
b010: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
b020: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
b030: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
b040: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
b050: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
b060: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
b070: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
b080: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
b090: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
b0a0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
b0b0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
b0c0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
b0d0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
b0e0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
b0f0: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
b100: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
b110: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
b120: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
b130: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
b140: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
b150: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
b160: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
b170: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
b180: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
b190: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
b1a0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
b1b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b1c0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
b1d0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
b1e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
b1f0: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
b200: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
b210: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
b220: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
b230: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
b240: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
b250: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
b260: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
b270: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
b280: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
b290: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
b2a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
b2b0: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
b2c0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
b2d0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
b2e0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
b2f0: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
b300: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
b310: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
b320: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
b330: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
b340: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
b350: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
b360: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b370: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
b380: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
b390: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
b3a0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
b3b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b3c0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
b3d0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
b3e0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
b3f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
b400: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
b410: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b420: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
b430: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
b440: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
b450: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
b460: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b470: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b480: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
b490: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
b4a0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
b4b0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
b4c0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
b4d0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
b4e0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
b4f0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
b500: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
b510: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
b520: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
b530: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
b540: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
b550: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
b560: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
b570: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b580: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b590: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
b5a0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
b5b0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
b5c0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
b5d0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
b5e0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
b5f0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
b600: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
b610: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
b620: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
b630: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
b640: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
b650: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
b660: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
b670: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
b680: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
b690: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b6a0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
b6b0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
b6c0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
b6d0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
b6e0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
b6f0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
b700: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b710: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
b720: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
b730: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
b740: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
b750: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
b760: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
b770: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
b780: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
b790: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
b7a0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
b7b0: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
b7c0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
b7d0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
b7e0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
b7f0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
b800: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
b810: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
b820: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b830: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b840: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
b850: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
b860: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b870: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
b880: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
b890: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
b8a0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
b8b0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
b8c0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
b8d0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
b8e0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
b8f0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
b900: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
b910: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
b920: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b930: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b940: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
b950: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
b960: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
b970: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
b980: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
b990: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
b9a0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b9b0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b9c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b9d0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b9e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b9f0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
ba00: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
ba10: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
ba20: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
ba30: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
ba40: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
ba50: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
ba60: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
ba70: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
ba80: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
ba90: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
baa0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
bab0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
bac0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
bad0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
bae0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
baf0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
bb00: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
bb10: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
bb20: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
bb30: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
bb40: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
bb50: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
bb60: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
bb70: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
bb80: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
bb90: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
bba0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
bbb0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
bbc0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
bbd0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
bbe0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
bbf0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
bc00: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
bc10: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
bc20: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
bc30: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
bc40: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
bc50: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
bc60: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
bc70: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
bc80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
bc90: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
bca0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
bcb0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
bcc0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
bcd0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
bce0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
bcf0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
bd00: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
bd10: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
bd20: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
bd30: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
bd40: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
bd50: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
bd60: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
bd70: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
bd80: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
bd90: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
bda0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
bdb0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
bdc0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
bdd0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
bde0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
bdf0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
be00: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
be10: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
be20: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
be30: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
be40: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
be50: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
be60: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
be70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
be80: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
be90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
bea0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
beb0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
bec0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
bed0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
bee0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
bef0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
bf00: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
bf10: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
bf20: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
bf30: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
bf40: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
bf50: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
bf60: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
bf70: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
bf80: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
bf90: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
bfa0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
bfb0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
bfc0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
bfd0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
bfe0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
bff0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
c000: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
c010: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
c020: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
c030: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
c040: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
c050: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
c060: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
c070: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
c080: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
c090: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
c0a0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
c0b0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
c0c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c0d0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
c0e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c0f0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
c100: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
c110: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
c120: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
c130: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
c140: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
c150: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
c160: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
c170: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
c180: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
c190: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
c1a0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
c1b0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
c1c0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
c1d0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
c1e0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
c1f0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
c200: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
c210: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
c220: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
c230: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
c240: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
c250: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
c260: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
c270: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
c280: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c290: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
c2a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c2b0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
c2c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
c2d0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
c2e0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
c2f0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
c300: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
c310: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
c320: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
c330: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
c340: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
c350: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
c360: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
c370: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
c380: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
c390: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
c3a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c3b0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
c3c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c3d0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
c3e0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
c3f0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
c400: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
c410: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
c420: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
c430: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
c440: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
c450: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
c460: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
c470: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
c480: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
c490: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
c4a0: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
c4b0: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
c4c0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
c4d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c4e0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
c4f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c500: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c510: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
c520: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
c530: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
c540: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
c550: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
c560: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
c570: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
c580: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
c590: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
c5a0: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
c5b0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
c5c0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
c5d0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
c5e0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
c5f0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
c600: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
c610: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
c620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
c630: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
c640: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
c650: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
c660: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
c670: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
c680: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
c690: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
c6a0: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
c6b0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
c6c0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
c6d0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
c6e0: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
c6f0: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
c700: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
c710: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
c720: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
c730: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
c740: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
c750: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
c760: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
c770: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
c780: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
c790: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
c7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
c7b0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
c7c0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c7d0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
c7e0: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
c7f0: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
c800: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
c810: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c820: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
c830: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
c840: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c850: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
c860: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c870: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
c880: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
c890: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
c8a0: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
c8b0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
c8c0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
c8d0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
c8e0: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
c8f0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
c900: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c910: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c920: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a  TOMIC_WRITE]].**
c930: 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   If the [SQLITE_
c940: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
c950: 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  IC_WRITE] opcode
c960: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
c970: 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  OK, then.** the 
c980: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
c990: 69 73 20 70 6c 61 63 65 64 20 69 6e 20 22 62 61  is placed in "ba
c9a0: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 22 2c  tch write mode",
c9b0: 20 77 68 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20   which.** means 
c9c0: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77  all subsequent w
c9d0: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
c9e0: 77 69 6c 6c 20 62 65 20 64 65 66 65 72 72 65 64  will be deferred
c9f0: 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f   and done.** ato
ca00: 6d 69 63 61 6c 6c 79 20 61 74 20 74 68 65 20 6e  mically at the n
ca10: 65 78 74 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  ext [SQLITE_FCNT
ca20: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
ca30: 57 52 49 54 45 5d 2e 20 20 53 79 73 74 65 6d 73  WRITE].  Systems
ca40: 0a 2a 2a 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  .** that do not 
ca50: 73 75 70 70 6f 72 74 20 62 61 74 63 68 20 61 74  support batch at
ca60: 6f 6d 69 63 20 77 72 69 74 65 73 20 77 69 6c 6c  omic writes will
ca70: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
ca80: 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c  OTFOUND..** ^Fol
ca90: 6c 6f 77 69 6e 67 20 61 20 73 75 63 63 65 73 73  lowing a success
caa0: 66 75 6c 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ful SQLITE_FCNTL
cab0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
cac0: 49 54 45 20 61 6e 64 20 70 72 69 6f 72 20 74 6f  ITE and prior to
cad0: 0a 2a 2a 20 74 68 65 20 63 6c 6f 73 69 6e 67 20  .** the closing 
cae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
caf0: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
cb00: 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  E] or.** [SQLITE
cb10: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
cb20: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53  ATOMIC_WRITE], S
cb30: 51 4c 69 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a  QLite will make.
cb40: 2a 2a 20 6e 6f 20 56 46 53 20 69 6e 74 65 72 66  ** no VFS interf
cb50: 61 63 65 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65  ace calls on the
cb60: 20 73 61 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66   same [sqlite3_f
cb70: 69 6c 65 5d 20 66 69 6c 65 20 64 65 73 63 72 69  ile] file descri
cb80: 70 74 6f 72 0a 2a 2a 20 65 78 63 65 70 74 20 66  ptor.** except f
cb90: 6f 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  or calls to the 
cba0: 78 57 72 69 74 65 20 6d 65 74 68 6f 64 20 61 6e  xWrite method an
cbb0: 64 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  d the xFileContr
cbc0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74  ol method.** wit
cbd0: 68 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  h [SQLITE_FCNTL_
cbe0: 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a  SIZE_HINT]..**.*
cbf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
cc00: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
cc10: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68  IC_WRITE]].** Th
cc20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
cc30: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
cc40: 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75 73  ITE] opcode caus
cc50: 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20  es all write.** 
cc60: 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63 65  operations since
cc70: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 75   the previous su
cc80: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
cc90: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e   .** [SQLITE_FCN
cca0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
ccb0: 57 52 49 54 45 5d 20 74 6f 20 62 65 20 70 65 72  WRITE] to be per
ccc0: 66 6f 72 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c  formed atomicall
ccd0: 79 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  y..** This file 
cce0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
ccf0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61  [SQLITE_OK] if a
cd00: 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 77  nd only if the w
cd10: 72 69 74 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c  rites were.** al
cd20: 6c 20 70 65 72 66 6f 72 6d 65 64 20 73 75 63 63  l performed succ
cd30: 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 68 61 76  essfully and hav
cd40: 65 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  e been committed
cd50: 20 74 6f 20 70 65 72 73 69 73 74 65 6e 74 20 73   to persistent s
cd60: 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61  torage..** ^Rega
cd70: 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
cd80: 72 20 6f 72 20 6e 6f 74 20 69 74 20 69 73 20 73  r or not it is s
cd90: 75 63 63 65 73 73 66 75 6c 2c 20 74 68 69 73 20  uccessful, this 
cda0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b  file control tak
cdb0: 65 73 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64  es.** the file d
cdc0: 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f 66  escriptor out of
cdd0: 20 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f 64   batch write mod
cde0: 65 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75  e so that all su
cdf0: 62 73 65 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74  bsequent.** writ
ce00: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  e operations are
ce10: 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a   independent..**
ce20: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
ce30: 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54  ver invoke SQLIT
ce40: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
ce50: 54 4f 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68  TOMIC_WRITE with
ce60: 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73  out.** a prior s
ce70: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
ce80: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
ce90: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cea0: 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  TE]..**.** <li>[
ceb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f  [SQLITE_FCNTL_RO
cec0: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52  LLBACK_ATOMIC_WR
ced0: 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ITE]].** The [SQ
cee0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
cef0: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
cf00: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  ] opcode causes 
cf10: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65  all write.** ope
cf20: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68  rations since th
cf30: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65  e previous succe
cf40: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a  ssful call to .*
cf50: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
cf60: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cf70: 54 45 5d 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64  TE] to be rolled
cf80: 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20   back..** ^This 
cf90: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b  file control tak
cfa0: 65 73 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  es the file desc
cfb0: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61  riptor out of ba
cfc0: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a  tch write mode.*
cfd0: 2a 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75  * so that all su
cfe0: 62 73 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f  bsequent write o
cff0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e  perations are in
d000: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53  dependent..** ^S
d010: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
d020: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46   invoke SQLITE_F
d030: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
d040: 4f 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f  OMIC_WRITE witho
d050: 75 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75  ut.** a prior su
d060: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
d070: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
d080: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
d090: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  E]..**.** <li>[[
d0a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
d0b0: 4b 5f 54 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54  K_TIMEOUT]].** T
d0c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d0d0: 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f  _LOCK_TIMEOUT] o
d0e0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 74 74  pcode causes att
d0f0: 65 6d 70 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a  empts to obtain.
d100: 2a 2a 20 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75  ** a file lock u
d110: 73 69 6e 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f  sing the xLock o
d120: 72 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  r xShmLock metho
d130: 64 73 20 6f 66 20 74 68 65 20 56 46 53 20 74 6f  ds of the VFS to
d140: 20 77 61 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20   wait.** for up 
d150: 74 6f 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  to M millisecond
d160: 73 20 62 65 66 6f 72 65 20 66 61 69 6c 69 6e 67  s before failing
d170: 2c 20 77 68 65 72 65 20 4d 20 69 73 20 74 68 65  , where M is the
d180: 20 73 69 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69   single .** unsi
d190: 67 6e 65 64 20 69 6e 74 65 67 65 72 20 70 61 72  gned integer par
d1a0: 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ameter..**.** <l
d1b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d1c0: 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a  _DATA_VERSION]].
d1d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d1e0: 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f  CNTL_DATA_VERSIO
d1f0: 4e 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  N] opcode is use
d200: 64 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  d to detect chan
d210: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61  ges to.** a data
d220: 62 61 73 65 20 66 69 6c 65 2e 20 20 54 68 65 20  base file.  The 
d230: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
d240: 69 6e 74 65 72 20 74 6f 20 61 20 33 32 2d 62 69  inter to a 32-bi
d250: 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
d260: 65 72 2e 0a 2a 2a 20 54 68 65 20 22 64 61 74 61  er..** The "data
d270: 20 76 65 72 73 69 6f 6e 22 20 66 6f 72 20 74 68   version" for th
d280: 65 20 70 61 67 65 72 20 69 73 20 77 72 69 74 74  e pager is writt
d290: 65 6e 20 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e  en into the poin
d2a0: 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61  ter.  The.** "da
d2b0: 74 61 20 76 65 72 73 69 6f 6e 22 20 63 68 61 6e  ta version" chan
d2c0: 67 65 73 20 77 68 65 6e 65 76 65 72 20 61 6e 79  ges whenever any
d2d0: 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73 20 74   change occurs t
d2e0: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
d2f0: 69 6e 67 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ing.** database 
d300: 66 69 6c 65 2c 20 65 69 74 68 65 72 20 74 68 72  file, either thr
d310: 6f 75 67 68 20 53 51 4c 20 73 74 61 74 65 6d 65  ough SQL stateme
d320: 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  nts on the same 
d330: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
d340: 65 63 74 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67  ection or throug
d350: 68 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  h transactions c
d360: 6f 6d 6d 69 74 74 65 64 20 62 79 20 73 65 70 61  ommitted by sepa
d370: 72 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  rate database.**
d380: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73   connections pos
d390: 73 69 62 6c 79 20 69 6e 20 6f 74 68 65 72 20 70  sibly in other p
d3a0: 72 6f 63 65 73 73 65 73 2e 20 54 68 65 20 5b 73  rocesses. The [s
d3b0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
d3c0: 6e 67 65 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  nges()].** inter
d3d0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
d3e0: 20 74 6f 20 66 69 6e 64 20 69 66 20 61 6e 79 20   to find if any 
d3f0: 64 61 74 61 62 61 73 65 20 6f 6e 20 74 68 65 20  database on the 
d400: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 63  connection has c
d410: 68 61 6e 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74  hanged,.** but t
d420: 68 61 74 20 69 6e 74 65 72 66 61 63 65 20 72 65  hat interface re
d430: 73 70 6f 6e 64 73 20 74 6f 20 63 68 61 6e 67 65  sponds to change
d440: 73 20 6f 6e 20 54 45 4d 50 20 61 73 20 77 65 6c  s on TEMP as wel
d450: 6c 20 61 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f  l as MAIN and do
d460: 65 73 0a 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64  es.** not provid
d470: 65 20 61 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f  e a mechanism to
d480: 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20   detect changes 
d490: 74 6f 20 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41  to MAIN only.  A
d4a0: 6c 73 6f 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  lso, the.** [sql
d4b0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
d4c0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
d4d0: 72 65 73 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65  responds to inte
d4e0: 72 6e 61 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c  rnal changes onl
d4f0: 79 20 61 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63  y and.** omits c
d500: 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 20 6f  hanges made by o
d510: 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63 6f  ther database co
d520: 6e 6e 65 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  nnections.  The.
d530: 2a 2a 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f  ** [PRAGMA data_
d540: 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64  version] command
d550: 20 70 72 6f 76 69 64 65 20 61 20 6d 65 63 68 61   provide a mecha
d560: 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63  nism to detect c
d570: 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73  hanges to.** a s
d580: 69 6e 67 6c 65 20 61 74 74 61 63 68 65 64 20 64  ingle attached d
d590: 61 74 61 62 61 73 65 20 74 68 61 74 20 6f 63 63  atabase that occ
d5a0: 75 72 20 64 75 65 20 74 6f 20 6f 74 68 65 72 20  ur due to other 
d5b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d5c0: 69 6f 6e 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69  ions,.** but omi
d5d0: 74 73 20 63 68 61 6e 67 65 73 20 69 6d 70 6c 65  ts changes imple
d5e0: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 64 61  mented by the da
d5f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d600: 6e 20 6f 6e 20 77 68 69 63 68 20 69 74 20 69 73  n on which it is
d610: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 54 68 69  .** called.  Thi
d620: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
d630: 73 20 74 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61  s the only mecha
d640: 6e 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63  nism to detect c
d650: 68 61 6e 67 65 73 20 74 68 61 74 0a 2a 2a 20 68  hanges that.** h
d660: 61 70 70 65 6e 20 65 69 74 68 65 72 20 69 6e 74  appen either int
d670: 65 72 6e 61 6c 6c 79 20 6f 72 20 65 78 74 65 72  ernally or exter
d680: 6e 61 6c 6c 79 20 61 6e 64 20 74 68 61 74 20 61  nally and that a
d690: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
d6a0: 74 68 0a 2a 2a 20 61 20 70 61 72 74 69 63 75 6c  th.** a particul
d6b0: 61 72 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ar attached data
d6c0: 62 61 73 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  base..** </ul>.*
d6d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d6e0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
d6f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
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 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
d720: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a  OXYFILE       2.
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 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
d750: 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23  XYFILE       3.#
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 4c 41 53 54 5f 45 52 52 4e 4f 20 20  NTL_LAST_ERRNO  
d780: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#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 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
d7b0: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
d7c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d7d0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
d7e0: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
d7f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d800: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
d810: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
d820: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d830: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
d840: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
d850: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
d860: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
d870: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
d880: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
d890: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
d8a0: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
d8b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
d8c0: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
d8d0: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
d8e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
d8f0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
d900: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
d910: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
d920: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
d930: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
d940: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
d950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d960: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
d970: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
d980: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
d990: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
d9a0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
d9b0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
d9c0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
d9d0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
d9e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
d9f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
da00: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20  FCNTL_TRACE     
da10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a               19.
da20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
da30: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20  CNTL_HAS_MOVED  
da40: 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23              20.#
da50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
da60: 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20  NTL_SYNC        
da70: 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64             21.#d
da80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
da90: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
daa0: 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65  WO        22.#de
dab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dac0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
dad0: 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66  LE       23.#def
dae0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
daf0: 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20  _WAL_BLOCK      
db00: 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69          24.#defi
db10: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
db20: 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20  ZIPVFS          
db30: 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e         25.#defin
db40: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  e SQLITE_FCNTL_R
db50: 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20  BU              
db60: 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65        26.#define
db70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
db80: 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  S_POINTER       
db90: 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20       27.#define 
dba0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
dbb0: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20  RNAL_POINTER    
dbc0: 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53      28.#define S
dbd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
dbe0: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_GET_HANDLE    
dbf0: 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51     29.#define SQ
dc00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20  LITE_FCNTL_PDB  
dc10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
dc20: 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    30.#define SQL
dc30: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
dc40: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
dc50: 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   31.#define SQLI
dc60: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
dc70: 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20  ATOMIC_WRITE    
dc80: 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  32.#define SQLIT
dc90: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
dca0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 33  _ATOMIC_WRITE  3
dcb0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
dcc0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45  _FCNTL_LOCK_TIME
dcd0: 4f 55 54 20 20 20 20 20 20 20 20 20 20 20 33 34  OUT           34
dce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dcf0: 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49  FCNTL_DATA_VERSI
dd00: 4f 4e 20 20 20 20 20 20 20 20 20 20 20 33 35 0a  ON           35.
dd10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dd20: 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20  CNTL_SIZE_LIMIT 
dd30: 20 20 20 20 20 20 20 20 20 20 20 20 33 36 0a 0a              36..
dd40: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61  /* deprecated na
dd50: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mes */.#define S
dd60: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
dd70: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
dd80: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
dd90: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
dda0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
ddb0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
ddc0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53    SQLITE_FCNTL_S
ddd0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
dde0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ddf0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
de00: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43         SQLITE_FC
de10: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a  NTL_LAST_ERRNO..
de20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
de30: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
de40: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
de50: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
de60: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
de70: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
de80: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
de90: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
dea0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
deb0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
dec0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
ded0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
dee0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
def0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
df00: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
df10: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
df20: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
df30: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
df40: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
df50: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
df60: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
df70: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
df80: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
df90: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
dfa0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
dfb0: 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20  I3REF: Loadable 
dfc0: 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a  Extension Thunk.
dfd0: 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
dfe0: 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71  to the opaque sq
dff0: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
e000: 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  es structure is 
e010: 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
e020: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
e030: 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73   to entry points
e040: 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78   of [loadable ex
e050: 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73  tensions].  This
e060: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75  .** structure mu
e070: 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20  st be typedefed 
e080: 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b  in order to work
e090: 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72   around compiler
e0a0: 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20   warnings.** on 
e0b0: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a  some platforms..
e0c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e0d0: 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
e0e0: 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61  utines sqlite3_a
e0f0: 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a  pi_routines;../*
e100: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
e110: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
e120: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
e130: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
e140: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
e150: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
e160: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
e170: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
e180: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
e190: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
e1a0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
e1b0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
e1c0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
e1d0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
e1e0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
e1f0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
e200: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
e210: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
e220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
e230: 2a 2a 20 54 68 65 20 56 46 53 20 69 6e 74 65 72  ** The VFS inter
e240: 66 61 63 65 20 69 73 20 73 6f 6d 65 74 69 6d 65  face is sometime
e250: 73 20 65 78 74 65 6e 64 65 64 20 62 79 20 61 64  s extended by ad
e260: 64 69 6e 67 20 6e 65 77 20 6d 65 74 68 6f 64 73  ding new methods
e270: 20 6f 6e 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64   onto.** the end
e280: 2e 20 20 45 61 63 68 20 74 69 6d 65 20 73 75 63  .  Each time suc
e290: 68 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f  h an extension o
e2a0: 63 63 75 72 73 2c 20 74 68 65 20 69 56 65 72 73  ccurs, the iVers
e2b0: 69 6f 6e 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20  ion field.** is 
e2c0: 69 6e 63 72 65 6d 65 6e 74 65 64 2e 20 20 54 68  incremented.  Th
e2d0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
e2e0: 20 73 74 61 72 74 65 64 20 6f 75 74 20 61 73 20   started out as 
e2f0: 31 20 69 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b  1 in.** SQLite [
e300: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f  version 3.5.0] o
e310: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d  n [dateof:3.5.0]
e320: 2c 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65 64  , then increased
e330: 20 74 6f 20 32 0a 2a 2a 20 77 69 74 68 20 53 51   to 2.** with SQ
e340: 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e  Lite [version 3.
e350: 37 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a  7.0] on [dateof:
e360: 33 2e 37 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e  3.7.0], and then
e370: 20 69 6e 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f   increased.** to
e380: 20 33 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b   3 with SQLite [
e390: 76 65 72 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f  version 3.7.6] o
e3a0: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d  n [dateof:3.7.6]
e3b0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
e3c0: 65 6c 64 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61  elds.** may be a
e3d0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65 20 73  ppended to the s
e3e0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e3f0: 74 20 61 6e 64 20 74 68 65 20 69 56 65 72 73 69  t and the iVersi
e400: 6f 6e 20 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20  on value.** may 
e410: 69 6e 63 72 65 61 73 65 20 61 67 61 69 6e 20 69  increase again i
e420: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
e430: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
e440: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
e450: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
e460: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
e470: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
e480: 74 68 65 20 74 72 61 6e 73 69 74 69 6f 6e 20 66  the transition f
e490: 72 6f 6d 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76  rom.** SQLite [v
e4a0: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f  ersion 3.5.9] to
e4b0: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d   [version 3.6.0]
e4c0: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e   on [dateof:3.6.
e4d0: 30 5d 0a 2a 2a 20 61 6e 64 20 79 65 74 20 74 68  0].** and yet th
e4e0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
e4f0: 20 77 61 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65   was not modifie
e500: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
e510: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
e520: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
e530: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
e540: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
e550: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
e560: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
e570: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
e580: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
e590: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
e5a0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
e5b0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
e5c0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
e5d0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
e5e0: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
e5f0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
e600: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
e610: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
e620: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
e630: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
e640: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
e650: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
e660: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
e670: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
e680: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
e690: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
e6a0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
e6b0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
e6c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
e6d0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
e6e0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
e6f0: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
e700: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
e710: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
e720: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
e730: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
e740: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
e750: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
e760: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
e770: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
e780: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
e790: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
e7a0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
e7b0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
e7c0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
e7d0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
e7e0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
e7f0: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
e800: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
e810: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
e820: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
e830: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
e840: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
e850: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
e860: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
e870: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
e880: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
e890: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
e8a0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
e8b0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
e8c0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
e8d0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
e8e0: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
e8f0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e900: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
e910: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
e920: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
e930: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
e940: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
e950: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
e960: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
e970: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
e980: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
e990: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
e9a0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
e9b0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
e9c0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
e9d0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
e9e0: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
e9f0: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
ea00: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
ea10: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
ea20: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
ea30: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
ea40: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
ea50: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
ea60: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
ea70: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
ea80: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
ea90: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
eaa0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
eab0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
eac0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
ead0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
eae0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
eaf0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
eb00: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
eb10: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
eb20: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
eb30: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
eb40: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
eb50: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
eb60: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
eb70: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
eb80: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
eb90: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
eba0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
ebb0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
ebc0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
ebd0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
ebe0: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
ebf0: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
ec00: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
ec10: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
ec20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
ec30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
ec40: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
ec50: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
ec60: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
ec70: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
ec80: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
ec90: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
eca0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
ecb0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
ecc0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
ecd0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
ece0: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
ecf0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
ed00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
ed10: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
ed20: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
ed30: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
ed40: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
ed50: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
ed60: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
ed70: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
ed80: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
ed90: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
eda0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
edb0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
edc0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
edd0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
ede0: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
edf0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
ee00: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
ee10: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
ee20: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ee30: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
ee40: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ee50: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
ee60: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ee70: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
ee80: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
ee90: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
eea0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
eeb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
eec0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
eed0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
eee0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
eef0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ef00: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
ef10: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
ef20: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
ef30: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
ef40: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
ef50: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
ef60: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
ef70: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
ef80: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
ef90: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
efa0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
efb0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
efc0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
efd0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
efe0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
eff0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
f000: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
f010: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
f020: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
f030: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
f040: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
f050: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
f060: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
f070: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
f080: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
f090: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
f0a0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
f0b0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
f0c0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
f0d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
f0e0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
f0f0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
f100: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
f110: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
f120: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
f130: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
f140: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
f150: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
f160: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
f170: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
f180: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
f190: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
f1a0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
f1b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
f1c0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
f1d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
f1e0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
f1f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
f200: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
f210: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
f220: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
f230: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
f240: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
f250: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
f260: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f270: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
f280: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
f290: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
f2a0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
f2b0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
f2c0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
f2d0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
f2e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
f2f0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
f300: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
f310: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
f320: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
f330: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
f340: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
f350: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
f360: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
f370: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
f380: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
f390: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
f3a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
f3b0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
f3c0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
f3d0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
f3e0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
f3f0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
f400: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
f410: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
f420: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
f430: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
f440: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
f450: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
f460: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
f470: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
f480: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
f490: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
f4a0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
f4b0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
f4c0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
f4d0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
f4e0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
f4f0: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
f500: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
f510: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
f520: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
f530: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
f540: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
f550: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
f560: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
f570: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
f580: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
f590: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
f5a0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
f5b0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
f5c0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
f5d0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
f5e0: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
f5f0: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
f600: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
f610: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
f620: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
f630: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
f640: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
f650: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
f660: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
f670: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
f680: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
f690: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
f6a0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
f6b0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
f6c0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
f6d0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
f6e0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
f6f0: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
f700: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
f710: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
f720: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
f730: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f740: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
f750: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
f760: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
f770: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f780: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
f790: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
f7a0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
f7b0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
f7c0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
f7d0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
f7e0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
f7f0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
f800: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
f810: 5f 41 43 43 45 53 53 5f 52 45 41 44 0a 2a 2a 20  _ACCESS_READ.** 
f820: 66 6c 61 67 20 69 73 20 6e 65 76 65 72 20 61 63  flag is never ac
f830: 74 75 61 6c 6c 79 20 75 73 65 64 20 61 6e 64 20  tually used and 
f840: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
f850: 65 64 20 69 6e 20 74 68 65 20 62 75 69 6c 74 2d  ed in the built-
f860: 69 6e 0a 2a 2a 20 56 46 53 65 73 20 6f 66 20 53  in.** VFSes of S
f870: 51 4c 69 74 65 2e 20 20 54 68 65 20 66 69 6c 65  QLite.  The file
f880: 20 69 73 20 6e 61 6d 65 64 20 62 79 20 74 68 65   is named by the
f890: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f8a0: 20 61 6e 64 20 63 61 6e 20 62 65 20 61 0a 2a 2a   and can be a.**
f8b0: 20 64 69 72 65 63 74 6f 72 79 2e 20 54 68 65 20   directory. The 
f8c0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 72  xAccess method r
f8d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
f8e0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
f8f0: 20 73 6f 6d 65 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72   some.** non-zer
f900: 6f 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 20  o error code if 
f910: 74 68 65 72 65 20 69 73 20 61 6e 20 49 2f 4f 20  there is an I/O 
f920: 65 72 72 6f 72 20 6f 72 20 69 66 20 74 68 65 20  error or if the 
f930: 6e 61 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66  name of.** the f
f940: 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  ile given in the
f950: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f960: 20 69 73 20 69 6c 6c 65 67 61 6c 2e 20 20 49 66   is illegal.  If
f970: 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 69 73   SQLITE_OK.** is
f980: 20 72 65 74 75 72 6e 65 64 2c 20 74 68 65 6e 20   returned, then 
f990: 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 20 7a 65 72 6f  non-zero or zero
f9a0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
f9b0: 20 2a 70 52 65 73 4f 75 74 20 74 6f 20 69 6e 64   *pResOut to ind
f9c0: 69 63 61 74 65 0a 2a 2a 20 77 68 65 74 68 65 72  icate.** whether
f9d0: 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65   or not the file
f9e0: 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 2e 20   is accessible. 
f9f0: 20 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20   .**.** ^SQLite 
fa00: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
fa10: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
fa20: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
fa30: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
fa40: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
fa50: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
fa60: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
fa70: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
fa80: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
fa90: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
faa0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
fab0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
fac0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
fad0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
fae0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
faf0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
fb00: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
fb10: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
fb20: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
fb30: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
fb40: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
fb50: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
fb60: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
fb70: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
fb80: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
fb90: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
fba0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
fbb0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
fbc0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
fbd0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
fbe0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
fbf0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
fc00: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
fc10: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
fc20: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
fc30: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
fc40: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
fc50: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
fc60: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
fc70: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
fc80: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
fc90: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
fca0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
fcb0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
fcc0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
fcd0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
fce0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
fcf0: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
fd00: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
fd10: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
fd20: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
fd30: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
fd40: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
fd50: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
fd60: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
fd70: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
fd80: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
fd90: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
fda0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
fdb0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
fdc0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
fdd0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
fde0: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
fdf0: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
fe00: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
fe10: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
fe20: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
fe30: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
fe40: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
fe50: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
fe60: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
fe70: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
fe80: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
fe90: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
fea0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
feb0: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
fec0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
fed0: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
fee0: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
fef0: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
ff00: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
ff10: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
ff20: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
ff30: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
ff40: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
ff50: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
ff60: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
ff70: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
ff80: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
ff90: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
ffa0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
ffb0: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
ffc0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
ffd0: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
ffe0: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
fff0: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
10000 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
10010 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
10020 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
10030 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
10040 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
10050 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
10060 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
10070 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
10080 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
10090 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
100a0 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
100b0 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
100c0 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
100d0 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
100e0 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
100f0 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
10100 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
10110 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
10120 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
10130 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
10140 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
10150 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
10160 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
10170 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
10180 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
10190 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
101a0 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
101b0 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
101c0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
101d0 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
101e0 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
101f0 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
10200 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
10210 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
10220 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
10230 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
10240 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
10250 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
10260 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
10270 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
10280 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
10290 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
102a0 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
102b0 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
102c0 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
102d0 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
102e0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
102f0 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
10300 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
10310 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
10320 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
10330 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
10340 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
10350 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
10360 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
10370 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
10380 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
10390 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
103a0 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
103b0 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
103c0 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
103d0 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
103e0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
103f0 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
10400 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
10410 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
10420 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
10430 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
10440 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
10450 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
10460 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
10470 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
10480 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
10490 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
104a0 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
104b0 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
104c0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
104d0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
104e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
104f0 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
10500 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
10510 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
10520 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
10530 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
10540 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10550 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
10560 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
10570 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
10580 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10590 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
105a0 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
105b0 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
105c0 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
105d0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
105e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
105f0 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
10600 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
10610 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
10620 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10630 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
10640 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
10650 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
10660 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
10670 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
10680 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
10690 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
106a0 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
106b0 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
106c0 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
106d0 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
106e0 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
106f0 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
10700 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
10710 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
10720 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
10730 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
10740 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
10750 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
10760 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
10770 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
10780 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
10790 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
107a0 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
107b0 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
107c0 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
107d0 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
107e0 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
107f0 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
10800 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
10810 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
10820 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
10830 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
10840 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
10850 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
10860 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
10870 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
10880 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
10890 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
108a0 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
108b0 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
108c0 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
108d0 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
108e0 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
108f0 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
10900 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
10910 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
10920 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10930 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
10940 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
10950 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
10960 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
10970 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
10980 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10990 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
109a0 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
109b0 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
109c0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
109d0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
109e0 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
109f0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
10a00 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
10a10 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
10a20 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
10a30 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
10a40 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
10a50 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
10a60 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
10a70 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
10a80 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
10a90 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
10aa0 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
10ab0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
10ac0 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
10ad0 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
10ae0 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
10af0 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
10b00 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
10b10 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
10b20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
10b30 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
10b40 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
10b50 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
10b60 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
10b70 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
10b80 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10b90 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
10ba0 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
10bb0 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
10bc0 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10bd0 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
10be0 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
10bf0 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
10c00 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
10c10 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
10c20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10c30 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
10c40 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
10c50 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
10c60 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
10c70 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
10c80 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
10c90 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
10ca0 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
10cb0 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
10cc0 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
10cd0 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
10ce0 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
10cf0 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
10d00 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
10d10 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
10d20 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
10d30 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
10d40 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
10d50 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
10d60 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
10d70 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
10d80 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
10d90 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10da0 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
10db0 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
10dc0 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
10dd0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10de0 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
10df0 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
10e00 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
10e10 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
10e20 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
10e30 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
10e40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10e50 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
10e60 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
10e70 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
10e80 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
10e90 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
10ea0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
10eb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10ec0 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
10ed0 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
10ee0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
10ef0 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
10f00 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
10f10 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
10f20 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
10f30 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
10f40 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
10f50 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
10f60 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
10f70 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
10f80 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
10f90 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
10fa0 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
10fb0 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
10fc0 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
10fd0 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
10fe0 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
10ff0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
11000 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
11010 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
11020 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
11030 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
11040 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
11050 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
11060 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
11070 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
11080 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
11090 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
110a0 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
110b0 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
110c0 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
110d0 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
110e0 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
110f0 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
11100 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
11110 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72  iven on the corr
11120 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
11130 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
11140 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
11150 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
11160 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
11170 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
11180 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
11190 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
111a0 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
111b0 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
111c0 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
111d0 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
111e0 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
111f0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
11200 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
11210 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
11220 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
11230 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
11240 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
11250 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
11260 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11270 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
11280 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
11290 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
112a0 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
112b0 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
112c0 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
112d0 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
112e0 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
112f0 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
11300 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
11310 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
11320 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
11330 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
11340 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
11350 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
11360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11370 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
11380 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
11390 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
113a0 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
113b0 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
113c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
113d0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
113e0 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
113f0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
11400 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
11410 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
11420 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
11430 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
11440 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
11450 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
11460 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
11470 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
11480 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
11490 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
114a0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
114b0 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
114c0 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
114d0 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
114e0 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
114f0 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
11500 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
11510 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
11520 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
11530 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
11540 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
11550 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
11560 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
11570 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
11580 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
11590 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
115a0 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
115b0 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
115c0 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
115d0 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
115e0 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
115f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11600 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
11610 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
11620 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
11630 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
11640 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
11650 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
11660 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
11670 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
11680 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
11690 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
116a0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
116b0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
116c0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
116d0 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
116e0 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
116f0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
11700 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
11710 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
11720 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
11730 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
11740 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
11750 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
11760 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11770 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
11780 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
11790 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
117a0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
117b0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
117c0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
117d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
117e0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
117f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11800 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
11810 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11820 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
11830 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
11840 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
11850 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
11860 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
11870 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
11880 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
11890 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
118a0 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
118b0 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
118c0 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
118d0 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
118e0 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
118f0 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
11900 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
11910 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
11920 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
11930 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
11940 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
11950 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
11960 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
11970 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
11980 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
11990 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
119a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
119b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
119c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
119d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
119e0 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
119f0 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
11a00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11a10 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
11a20 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
11a30 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
11a40 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
11a50 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
11a60 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
11a70 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
11a80 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
11a90 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
11aa0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
11ab0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
11ac0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11ad0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
11ae0 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
11af0 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
11b00 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
11b10 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
11b20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
11b30 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
11b40 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
11b50 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11b60 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
11b70 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
11b80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
11b90 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
11ba0 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
11bb0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
11bc0 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
11bd0 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
11be0 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
11bf0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
11c00 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
11c10 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
11c20 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
11c30 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
11c40 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11c50 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
11c60 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
11c70 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
11c80 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
11c90 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
11ca0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
11cb0 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
11cc0 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
11cd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
11ce0 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
11cf0 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
11d00 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
11d10 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
11d20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11d30 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
11d40 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
11d50 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
11d60 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
11d70 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
11d80 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11d90 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
11da0 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
11db0 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
11dc0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
11dd0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
11de0 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
11df0 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
11e00 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
11e10 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
11e20 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
11e30 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11e40 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
11e50 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
11e60 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
11e70 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
11e80 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
11e90 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
11ea0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
11eb0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
11ec0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
11ed0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
11ee0 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
11ef0 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
11f00 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
11f10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11f20 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
11f30 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
11f40 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
11f50 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
11f60 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
11f70 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
11f80 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
11f90 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
11fa0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
11fb0 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
11fc0 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
11fd0 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
11fe0 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
11ff0 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
12000 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
12010 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
12020 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
12030 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
12040 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
12050 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
12060 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
12070 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
12080 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
12090 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
120a0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
120b0 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
120c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
120d0 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
120e0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
120f0 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
12100 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
12110 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
12120 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
12130 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
12140 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
12150 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12160 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
12170 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
12180 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
12190 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
121a0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
121b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
121c0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
121d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
121e0 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
121f0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
12200 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
12210 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
12220 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
12230 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
12240 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
12250 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
12260 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
12270 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
12280 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
12290 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
122a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
122b0 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
122c0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
122d0 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
122e0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
122f0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
12300 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
12310 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
12320 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
12330 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12340 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
12350 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
12360 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
12370 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
12380 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
12390 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
123a0 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
123b0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
123c0 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
123d0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
123e0 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
123f0 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
12400 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
12410 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
12420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
12430 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
12440 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
12450 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
12460 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
12470 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
12480 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
12490 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
124a0 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
124b0 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
124c0 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
124d0 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
124e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
124f0 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
12500 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
12510 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
12520 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
12530 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
12540 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
12550 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
12560 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
12570 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
12580 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
12590 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
125a0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68  eds..**.** <b>Th
125b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
125c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
125d0 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
125e0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
125f0 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  ** must ensure t
12600 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
12610 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
12620 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
12630 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
12640 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
12650 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
12660 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  .</b>.**.** The 
12670 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12680 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61   interface.** ma
12690 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
126a0 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
126b0 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
126c0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
126d0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
126e0 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
126f0 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
12700 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
12710 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
12720 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
12730 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
12740 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
12750 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
12760 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
12770 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
12780 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
12790 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
127a0 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
127b0 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
127c0 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
127d0 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
127e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
127f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
12800 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
12810 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
12820 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12830 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
12840 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
12850 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
12860 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
12870 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
12880 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
12890 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
128a0 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
128b0 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
128c0 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
128d0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
128e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
128f0 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
12900 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
12910 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
12920 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12930 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
12940 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
12950 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
12960 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
12970 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
12980 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
12990 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
129a0 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
129b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
129c0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
129d0 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
129e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
129f0 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
12a00 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
12a10 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
12a20 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  nections.** METH
12a30 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
12a40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
12a50 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
12a60 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
12a70 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
12a80 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
12a90 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
12aa0 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
12ab0 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
12ac0 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
12ad0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
12ae0 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
12af0 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
12b00 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
12b10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
12b20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
12b30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
12b40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
12b50 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
12b60 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
12b70 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
12b80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
12b90 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
12ba0 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
12bb0 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
12bc0 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
12bd0 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
12be0 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
12bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12c00 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
12c10 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
12c20 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
12c30 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
12c40 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
12c50 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
12c60 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
12c70 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
12c80 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
12c90 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
12ca0 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
12cb0 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
12cc0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
12cd0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
12ce0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
12cf0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
12d00 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
12d10 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
12d20 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
12d30 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
12d40 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
12d50 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
12d60 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
12d70 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
12d80 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12d90 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
12da0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
12db0 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
12dc0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
12dd0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
12de0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
12df0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12e00 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
12e10 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
12e20 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
12e30 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
12e40 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
12e50 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
12e60 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
12e70 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12e80 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
12e90 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
12ea0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
12eb0 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
12ec0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
12ed0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
12ee0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
12ef0 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
12f00 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
12f10 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
12f20 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
12f30 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
12f40 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
12f50 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
12f60 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
12f70 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
12f80 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
12f90 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
12fa0 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
12fb0 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
12fc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12fd0 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
12fe0 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
12ff0 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
13000 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
13010 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
13020 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
13030 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
13040 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
13050 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
13060 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
13070 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
13080 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13090 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
130a0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
130b0 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
130c0 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
130d0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
130e0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
130f0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
13100 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
13110 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
13120 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
13130 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
13140 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
13150 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
13160 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
13170 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
13180 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
13190 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
131a0 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
131b0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
131c0 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
131d0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
131e0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
131f0 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
13200 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
13210 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
13220 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
13230 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
13240 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
13250 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
13260 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
13270 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
13280 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
13290 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
132a0 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
132b0 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
132c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
132d0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
132e0 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
132f0 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
13300 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
13310 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
13320 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
13330 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
13340 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
13350 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
13360 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
13370 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
13380 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
13390 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
133a0 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
133b0 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
133c0 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
133d0 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
133e0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
133f0 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
13400 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
13410 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
13420 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
13430 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
13440 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
13450 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
13460 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
13470 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
13480 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
13490 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
134a0 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
134b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
134c0 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
134d0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
134e0 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
134f0 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
13500 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
13510 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
13520 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
13530 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
13540 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
13550 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
13560 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
13570 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
13580 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a    For example,.*
13590 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
135a0 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
135b0 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
135c0 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
135d0 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
135e0 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
135f0 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
13600 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
13610 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
13620 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
13630 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
13640 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
13650 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
13660 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
13670 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
13680 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
13690 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
136a0 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
136b0 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
136c0 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
136d0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
136e0 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
136f0 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
13700 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
13710 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
13720 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
13730 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
13740 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
13750 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
13760 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
13770 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
13780 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
13790 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
137a0 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
137b0 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
137c0 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
137d0 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
137e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
137f0 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
13800 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
13810 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13820 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
13830 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
13840 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
13850 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
13860 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
13870 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
13880 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
13890 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
138a0 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
138b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
138c0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
138d0 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
138e0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
138f0 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
13900 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
13910 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
13920 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
13930 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
13940 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
13950 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
13960 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
13970 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
13980 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
13990 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
139a0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
139b0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
139c0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
139d0 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
139e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
139f0 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
13a00 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
13a10 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
13a20 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
13a30 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
13a40 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
13a50 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
13a60 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
13a70 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
13a80 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
13a90 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
13aa0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
13ab0 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
13ac0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
13ad0 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
13ae0 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
13af0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
13b00 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
13b10 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
13b20 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
13b30 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
13b40 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
13b50 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
13b60 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
13b70 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
13b80 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
13b90 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
13ba0 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
13bb0 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
13bc0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
13bd0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
13be0 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
13bf0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
13c00 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
13c10 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
13c20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
13c30 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
13c40 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
13c50 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
13c60 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
13c70 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
13c80 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
13c90 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
13ca0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13cb0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
13cc0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
13cd0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13ce0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
13cf0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
13d00 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
13d10 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
13d20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
13d30 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
13d40 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
13d50 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
13d60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13d70 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
13d80 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
13d90 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
13da0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
13db0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
13dc0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13dd0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
13de0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
13df0 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
13e00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13e10 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
13e20 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
13e30 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
13e40 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
13e50 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
13e60 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
13e70 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
13e80 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
13e90 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13ea0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
13eb0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13ec0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
13ed0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
13ee0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
13ef0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
13f00 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
13f10 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
13f20 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13f30 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
13f40 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
13f50 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
13f60 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
13f70 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
13f80 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
13f90 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
13fa0 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
13fb0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
13fc0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13fd0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13fe0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13ff0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14000 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14010 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14020 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
14030 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
14040 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
14050 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
14060 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
14070 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
14080 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
14090 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
140a0 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
140b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
140c0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
140d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
140e0 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
140f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14100 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
14110 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14120 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
14130 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
14140 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
14150 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
14160 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
14170 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
14180 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
14190 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
141a0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
141b0 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
141c0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
141d0 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
141e0 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
141f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
14200 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
14210 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
14220 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
14230 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
14240 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
14250 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
14260 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14270 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
14280 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
14290 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
142a0 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
142b0 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
142c0 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
142d0 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
142e0 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
142f0 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
14300 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
14310 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
14320 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
14330 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14340 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
14350 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
14360 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14370 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14380 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14390 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
143a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
143b0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
143c0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
143d0 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
143e0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
143f0 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
14400 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14410 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
14420 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
14430 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
14440 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
14450 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
14460 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14470 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
14480 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14490 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
144a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
144b0 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
144c0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
144d0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
144e0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
144f0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
14500 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
14510 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
14520 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
14530 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
14540 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
14550 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
14560 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
14570 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
14580 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14590 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
145a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
145b0 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
145c0 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
145d0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
145e0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
145f0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
14600 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14610 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
14620 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
14630 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
14640 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
14650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
14660 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
14670 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
14680 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
14690 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
146a0 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
146b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
146c0 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
146d0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
146e0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
146f0 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
14700 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
14710 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
14720 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14730 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14740 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14750 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
14760 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14770 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
14780 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
14790 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
147a0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
147b0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
147c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
147d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
147e0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
147f0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
14800 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14810 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
14820 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
14830 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14840 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14850 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
14860 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
14870 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14880 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
14890 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
148a0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
148b0 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
148c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
148d0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
148e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
148f0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14900 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
14910 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
14920 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
14930 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
14940 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
14950 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
14960 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
14970 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14980 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
14990 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
149a0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
149b0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
149c0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
149d0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
149e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
149f0 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
14a00 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
14a10 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
14a20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
14a30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14a40 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
14a50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14a60 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
14a70 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14a90 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
14aa0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14ab0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
14ac0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14ad0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14ae0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14af0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14b00 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  e..** The [sqlit
14b10 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
14b20 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
14b30 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
14b40 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
14b50 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
14b60 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
14b70 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
14b80 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
14b90 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
14ba0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
14bb0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
14bc0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
14bd0 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
14be0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14bf0 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
14c00 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
14c10 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
14c20 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
14c30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14c40 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  MALL_MALLOC]] <d
14c50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14c60 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  SMALL_MALLOC</dt
14c70 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
14c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
14c90 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  LL_MALLOC option
14ca0 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
14cb0 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70  gument of.** typ
14cc0 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
14cd0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
14ce0 20 77 68 69 63 68 20 69 66 20 74 72 75 65 20 70   which if true p
14cf0 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20 74  rovides a hint t
14d00 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74  o.** SQLite that
14d10 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64   it should avoid
14d20 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c   large memory al
14d30 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73  locations if pos
14d40 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65  sible..** SQLite
14d50 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72   will run faster
14d60 20 69 66 20 69 74 20 69 73 20 66 72 65 65 20 74   if it is free t
14d70 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d  o make large mem
14d80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c  ory allocations,
14d90 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70  .** but some app
14da0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70  lication might p
14db0 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f  refer to run slo
14dc0 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20  wer in exchange 
14dd0 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  for.** guarantee
14de0 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66  s about memory f
14df0 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  ragmentation tha
14e00 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69  t are possible i
14e10 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63  f large.** alloc
14e20 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64  ations are avoid
14e30 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  ed.  This hint i
14e40 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a  s normally off..
14e50 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14e60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14e70 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
14e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
14e90 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
14ea0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
14eb0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
14ec0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
14ed0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
14ee0 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e   type int,.** in
14ef0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
14f00 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
14f10 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
14f20 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
14f30 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c   of.** memory al
14f40 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
14f50 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
14f60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
14f70 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20  atistics are.** 
14f80 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f  disabled, the fo
14f90 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
14fa0 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
14fb0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
14fc0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
14fd0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
14fe0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
14ff0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
15000 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
15010 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
15020 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
15030 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
15040 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
15050 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20  status64()].**  
15060 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
15070 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
15080 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
15090 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
150a0 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
150b0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
150c0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
150d0 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
150e0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
150f0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
15100 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
15110 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
15120 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
15130 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15140 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
15150 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15160 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
15170 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
15180 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
15190 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f   option is no lo
151a0 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f  nger used..** </
151b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
151c0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
151d0 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
151e0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
151f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
15200 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15210 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
15220 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d  on specifies a m
15230 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68  emory pool.** th
15240 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
15250 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  e for the databa
15260 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
15270 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
15280 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
15290 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
152a0 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
152b0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61  tion option is a
152c0 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70   no-op if an app
152d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
152e0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
152f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
15300 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
15310 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15320 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68  PCACHE2]..** ^Th
15330 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
15340 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
15350 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
15360 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
15370 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
15380 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29  ed memory (pMem)
15390 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
153a0 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69  ch page cache li
153b0 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  ne (sz),.** and 
153c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61  the number of ca
153d0 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a  che lines (N)..*
153e0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
153f0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
15400 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
15410 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
15420 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
15430 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
15440 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
15450 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
15460 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
15470 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
15480 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
15490 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
154a0 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
154b0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
154c0 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c  mined using [SQL
154d0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
154e0 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74  E_HDRSZ]..** ^It
154f0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
15500 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
15510 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
15520 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
15530 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
15540 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
15550 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72    The pMem.** ar
15560 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65  gument must be e
15570 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
15580 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65  nter or a pointe
15590 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  r to an 8-byte.*
155a0 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  * aligned block 
155b0 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  of memory of at 
155c0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
155d0 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73  , otherwise.** s
155e0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
155f0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
15600 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69  .** ^When pMem i
15610 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
15620 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74  te will strive t
15630 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  o use the memory
15640 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20   provided.** to 
15650 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63  satisfy page cac
15660 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e  he needs, fallin
15670 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74  g back to [sqlit
15680 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a  e3_malloc()] if.
15690 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20  ** a page cache 
156a0 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74  line is larger t
156b0 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20  han sz bytes or 
156c0 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d  if all of the pM
156d0 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  em buffer.** is 
156e0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49  exhausted..** ^I
156f0 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61  f pMem is NULL a
15700 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  nd N is non-zero
15710 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61  , then each data
15720 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15730 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69  ** does an initi
15740 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69  al bulk allocati
15750 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  on for page cach
15760 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d  e memory.** from
15770 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15780 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66  ()] sufficient f
15790 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73  or N cache lines
157a0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
157b0 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34  e or.** of -1024
157c0 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73  *N bytes if N is
157d0 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66   negative, . ^If
157e0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
157f0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
15800 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
15810 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
15820 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61  ed by the initia
15830 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  l.** allocation,
15840 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65   then SQLite goe
15850 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
15860 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65  lloc()] separate
15870 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61  ly for each.** a
15880 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20  dditional cache 
15890 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  line. </dd>.**.*
158a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
158b0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
158c0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
158d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
158e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
158f0 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
15900 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
15910 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
15920 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
15930 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
15940 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
15950 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
15960 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
15970 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
15980 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
15990 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
159a0 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
159b0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
159c0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
159d0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
159e0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
159f0 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
15a00 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
15a10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
15a20 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
15a30 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
15a40 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
15a50 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
15a60 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
15a70 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
15a80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
15a90 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
15aa0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
15ab0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
15ac0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
15ad0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
15ae0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
15af0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
15b00 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
15b10 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
15b20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
15b30 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
15b40 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
15b50 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
15b60 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
15b70 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
15b80 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
15b90 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
15ba0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
15bb0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
15bc0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
15bd0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
15be0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
15bf0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
15c00 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
15c10 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
15c20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
15c30 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
15c40 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
15c50 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
15c60 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
15c70 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
15c80 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
15c90 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
15ca0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
15cb0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
15cc0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
15cd0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
15ce0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
15cf0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
15d00 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
15d10 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
15d20 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
15d30 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
15d40 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
15d50 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
15d60 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
15d70 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
15d80 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15d90 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
15da0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
15db0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
15dc0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15dd0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
15de0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15df0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15e00 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
15e10 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
15e20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15e30 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15e40 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
15e50 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
15e60 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
15e70 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
15e80 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
15e90 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
15ea0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
15eb0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
15ec0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
15ed0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
15ee0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
15ef0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15f00 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15f10 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
15f20 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
15f30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
15f40 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
15f50 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
15f60 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
15f70 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
15f80 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15f90 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
15fa0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
15fb0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
15fc0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
15fd0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
15fe0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
15ff0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
16000 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
16010 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
16020 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
16030 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16040 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
16050 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
16060 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
16070 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16080 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
16090 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
160a0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
160b0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
160c0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
160d0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
160e0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
160f0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
16100 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
16110 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
16120 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
16130 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
16140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
16150 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
16160 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
16170 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
16180 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
16190 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
161a0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
161b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
161c0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
161d0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
161e0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
161f0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
16200 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
16210 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
16220 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
16230 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
16240 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
16250 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
16260 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
16270 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
16280 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
16290 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
162a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
162b0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
162c0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
162d0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
162e0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
162f0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
16300 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
16310 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
16320 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
16330 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
16340 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16350 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
16360 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
16370 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16380 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16390 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
163a0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
163b0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
163c0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
163d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
163e0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
163f0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
16400 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
16410 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
16420 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
16430 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
16440 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
16450 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16460 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
16470 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
16480 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
16490 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
164a0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
164b0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
164c0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
164d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
164e0 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
164f0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
16500 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
16510 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
16520 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
16530 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16540 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
16550 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
16560 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
16570 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
16580 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
16590 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
165a0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
165b0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
165c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
165d0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
165e0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
165f0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
16600 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16610 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16620 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
16630 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
16640 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
16650 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
16660 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
16670 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16680 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
16690 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
166a0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
166b0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
166c0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
166d0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
166e0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
166f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
16700 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
16710 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
16720 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16730 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
16740 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16750 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
16760 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
16770 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16780 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
16790 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
167a0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
167b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
167c0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
167d0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
167e0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
167f0 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
16800 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
16810 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
16820 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
16830 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
16840 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16850 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
16860 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
16870 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
16880 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
16890 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
168a0 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
168b0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
168c0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
168d0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
168e0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
168f0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
16900 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
16910 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
16920 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
16930 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
16940 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
16950 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
16960 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
16970 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
16980 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
16990 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
169a0 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
169b0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
169c0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
169d0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
169e0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
169f0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
16a00 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
16a10 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
16a20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
16a30 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
16a40 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
16a50 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
16a60 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
16a70 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
16a80 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
16a90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
16aa0 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
16ab0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
16ac0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
16ad0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
16ae0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
16af0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
16b00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
16b10 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
16b20 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
16b30 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
16b40 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
16b50 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
16b60 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
16b70 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
16b80 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
16b90 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
16ba0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
16bb0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
16bc0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16bd0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
16be0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
16bf0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
16c00 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
16c10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
16c20 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
16c30 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
16c40 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
16c50 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
16c60 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
16c70 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
16c80 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
16c90 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
16ca0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
16cb0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
16cc0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
16cd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16ce0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
16cf0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
16d00 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
16d10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
16d30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16d40 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
16d50 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
16d60 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
16d70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
16d80 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
16d90 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
16da0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
16db0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
16dc0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
16dd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
16de0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
16df0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16e00 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
16e10 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
16e20 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
16e30 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
16e40 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
16e50 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
16e60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
16e70 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
16e80 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
16e90 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
16ea0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
16eb0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
16ec0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
16ed0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
16ee0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
16ef0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
16f00 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
16f10 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
16f20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
16f30 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
16f40 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
16f50 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
16f60 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
16f70 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
16f80 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
16f90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
16fa0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
16fb0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
16fc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
16fd0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
16fe0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
16ff0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
17000 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
17010 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
17020 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
17030 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
17040 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
17050 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
17060 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
17070 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
17080 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
17090 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
170a0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
170b0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
170c0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
170d0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
170e0 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
170f0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
17100 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
17110 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
17120 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
17130 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
17140 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17150 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
17160 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
17170 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
17180 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
17190 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
171a0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
171b0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
171c0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
171d0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
171e0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
171f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17200 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
17210 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
17220 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
17230 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
17240 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
17250 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
17260 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
17270 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
17280 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
17290 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
172a0 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
172b0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
172c0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
172d0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
172e0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
172f0 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
17300 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
17310 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
17320 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
17330 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
17340 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
17350 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
17360 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
17370 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
17380 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
17390 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
173a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
173b0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
173c0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
173d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
173e0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
173f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17400 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
17410 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
17420 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
17430 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
17440 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
17450 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
17460 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
17470 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
17480 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
17490 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
174a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
174b0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
174c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
174d0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
174e0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
174f0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
17500 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
17510 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
17520 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
17530 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
17540 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
17550 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
17560 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
17570 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
17580 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
17590 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
175a0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
175b0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
175c0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
175d0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
175e0 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
175f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
17600 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
17610 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
17620 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
17630 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
17640 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
17650 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
17660 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
17670 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
17680 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
17690 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
176a0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
176b0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
176c0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
176d0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
176e0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
176f0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
17700 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
17710 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
17720 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
17730 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
17740 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
17750 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
17760 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
17770 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
17780 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
17790 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
177a0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
177b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
177c0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
177d0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
177e0 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
177f0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
17800 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
17810 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
17820 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
17830 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
17840 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
17850 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
17860 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
17870 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
17880 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
17890 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
178a0 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
178b0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
178c0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
178d0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
178e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
178f0 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
17900 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17910 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
17920 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
17930 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
17940 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
17950 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
17960 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
17970 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
17980 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
17990 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
179a0 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
179b0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
179c0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
179d0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
179e0 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
179f0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
17a00 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
17a10 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
17a20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17a30 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
17a40 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
17a50 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
17a60 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
17a70 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
17a80 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
17a90 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
17aa0 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
17ab0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
17ac0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
17ad0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
17ae0 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
17af0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
17b00 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
17b10 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
17b20 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
17b30 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
17b40 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
17b50 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17b60 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
17b70 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
17b80 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
17b90 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
17ba0 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
17bb0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
17bc0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
17bd0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
17be0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17bf0 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
17c00 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17c10 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17c20 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
17c30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
17c40 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
17c50 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
17c60 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
17c70 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
17c80 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
17c90 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
17ca0 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
17cb0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
17cc0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
17cd0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
17ce0 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
17cf0 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
17d00 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
17d10 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
17d20 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
17d30 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
17d40 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
17d50 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17d60 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
17d70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
17d80 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
17d90 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17da0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
17db0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
17dc0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
17dd0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
17de0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
17df0 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
17e00 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
17e10 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
17e20 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
17e30 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
17e40 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
17e50 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
17e60 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
17e70 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
17e80 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
17e90 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
17ea0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
17eb0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
17ec0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
17ed0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
17ee0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
17ef0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
17f00 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17f10 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
17f20 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17f30 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
17f40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17f50 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
17f60 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
17f70 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
17f80 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
17f90 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
17fa0 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
17fb0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
17fc0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
17fd0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
17fe0 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
17ff0 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
18000 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
18010 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
18020 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
18030 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
18040 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
18050 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
18060 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
18070 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
18080 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
18090 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
180a0 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
180b0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
180c0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
180d0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
180e0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
180f0 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
18100 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
18110 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
18120 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
18130 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  value..**.** [[S
18140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
18150 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a  TJRNL_SPILL]].**
18160 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
18170 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
18180 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  L.** <dd>^The SQ
18190 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
181a0 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f  JRNL_SPILL optio
181b0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
181c0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
181d0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20  .** becomes the 
181e0 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [statement journ
181f0 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73  al] spill-to-dis
18200 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a  k threshold.  .*
18210 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75  * [Statement jou
18220 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20  rnals] are held 
18230 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20  in memory until 
18240 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62  their size (in b
18250 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73  ytes).** exceeds
18260 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c   this threshold,
18270 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20   at which point 
18280 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e  they are written
18290 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20   to disk..** Or 
182a0 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64  if the threshold
182b0 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e   is -1, statemen
182c0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61  t journals are a
182d0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78  lways held.** ex
182e0 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d  clusively in mem
182f0 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61  ory..** Since ma
18300 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  ny statement jou
18310 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f  rnals never beco
18320 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e  me large, settin
18330 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74  g the spill.** t
18340 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61  hreshold to a va
18350 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69  lue such as 64Ki
18360 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65  B can greatly re
18370 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20  duce the amount 
18380 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72  of.** I/O requir
18390 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74  ed to support st
183a0 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b  atement rollback
183b0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
183c0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
183d0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72  setting is contr
183e0 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  olled by the.** 
183f0 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c  [SQLITE_STMTJRNL
18400 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d  _SPILL] compile-
18410 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a  time option..**.
18420 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
18430 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a  IG_SORTERREF_SIZ
18440 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
18450 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52  E_CONFIG_SORTERR
18460 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54  EF_SIZE.** <dd>T
18470 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
18480 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20  _SORTERREF_SIZE 
18490 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61  option accepts a
184a0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
184b0 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 6e  r.** of type (in
184c0 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76 61 6c  t) - the new val
184d0 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74 65 72  ue of the sorter
184e0 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20  -reference size 
184f0 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73  threshold..** Us
18500 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69  ually, when SQLi
18510 74 65 20 75 73 65 73 20 61 6e 20 65 78 74 65 72  te uses an exter
18520 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 65  nal sort to orde
18530 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f 72 64  r records accord
18540 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44  ing.** to an ORD
18550 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20 61 6c  ER BY clause, al
18560 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69 72 65  l fields require
18570 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20  d by the caller 
18580 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20 74  are present in t
18590 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 63  he.** sorted rec
185a0 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 69  ords. However, i
185b0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
185c0 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74 68 65  nes based on the
185d0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 0a 2a   declared type.*
185e0 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63 6f 6c  * of a table col
185f0 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76 61 6c  umn that its val
18600 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74  ues are likely t
18610 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67 65 20  o be very large 
18620 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e  - larger.** than
18630 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20   the configured 
18640 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65  sorter-reference
18650 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 20   size threshold 
18660 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72 65 6e  - then a referen
18670 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 20  ce.** is stored 
18680 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64 20 72  in each sorted r
18690 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20 72 65  ecord and the re
186a0 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61  quired column va
186b0 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66  lues loaded.** f
186c0 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65  rom the database
186d0 20 61 73 20 72 65 63 6f 72 64 73 20 61 72 65 20   as records are 
186e0 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 74  returned in sort
186f0 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20 64 65  ed order. The de
18700 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66  fault.** value f
18710 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  or this option i
18720 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65 20 74  s to never use t
18730 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  his optimization
18740 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61 20 0a  . Specifying a .
18750 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ** negative valu
18760 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f  e for this optio
18770 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65 20 64  n restores the d
18780 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 75 72  efault behaviour
18790 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ..** This option
187a0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
187b0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
187c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
187d0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
187e0 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 52  BLE_SORTER_REFER
187f0 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74  ENCES] compile-t
18800 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ime option..**.*
18810 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
18820 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 5d  G_MEMDB_MAXSIZE]
18830 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
18840 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58  CONFIG_MEMDB_MAX
18850 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  SIZE.** <dd>The 
18860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
18870 4d 44 42 5f 4d 41 58 53 49 5a 45 20 6f 70 74 69  MDB_MAXSIZE opti
18880 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73 69 6e  on accepts a sin
18890 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  gle parameter.**
188a0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d   [sqlite3_int64]
188b0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
188c0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
188d0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 66 6f 72  maximum size for
188e0 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a   an in-memory.**
188f0 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
18900 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
18910 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29 5d 2e  _deserialize()].
18920 20 20 54 68 69 73 20 64 65 66 61 75 6c 74 20 6d    This default m
18930 61 78 69 6d 75 6d 0a 2a 2a 20 73 69 7a 65 20 63  aximum.** size c
18940 61 6e 20 62 65 20 61 64 6a 75 73 74 65 64 20 75  an be adjusted u
18950 70 20 6f 72 20 64 6f 77 6e 20 66 6f 72 20 69 6e  p or down for in
18960 64 69 76 69 64 75 61 6c 20 64 61 74 61 62 61 73  dividual databas
18970 65 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  es using the.** 
18980 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
18990 5a 45 5f 4c 49 4d 49 54 5d 20 5b 73 71 6c 69 74  ZE_LIMIT] [sqlit
189a0 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 7c  e3_file_control|
189b0 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 5d 2e 20 20  file-control].  
189c0 49 66 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  If this.** confi
189d0 67 75 72 61 74 69 6f 6e 20 73 65 74 74 69 6e 67  guration setting
189e0 20 69 73 20 6e 65 76 65 72 20 75 73 65 64 2c 20   is never used, 
189f0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
18a00 20 6d 61 78 69 6d 75 6d 20 69 73 20 64 65 74 65   maximum is dete
18a10 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
18a20 20 5b 53 51 4c 49 54 45 5f 4d 45 4d 44 42 5f 44   [SQLITE_MEMDB_D
18a30 45 46 41 55 4c 54 5f 4d 41 58 53 49 5a 45 5d 20  EFAULT_MAXSIZE] 
18a40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
18a50 69 6f 6e 2e 20 20 49 66 20 74 68 61 74 0a 2a 2a  ion.  If that.**
18a60 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
18a70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 73 65 74 2c  tion is not set,
18a80 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
18a90 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 31 30 37  t maximum is 107
18aa0 33 37 34 31 38 32 34 2e 0a 2a 2a 20 3c 2f 64 6c  3741824..** </dl
18ab0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
18ac0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
18ad0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
18ae0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
18af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
18b00 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
18b10 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
18b20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
18b30 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
18b40 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
18b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
18b60 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
18b70 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
18b80 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
18b90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18ba0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
18bb0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
18bc0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
18bd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18be0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
18bf0 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  6  /* No longer 
18c00 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
18c10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
18c20 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
18c30 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
18c40 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
18c50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18c60 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
18c70 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
18c80 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
18c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18ca0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
18cb0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
18cc0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
18cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
18ce0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
18cf0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
18d00 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
18d10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18d20 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
18d30 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
18d40 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
18d50 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
18d60 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
18d70 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
18d80 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
18d90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18da0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
18db0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
18dc0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
18dd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
18de0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
18df0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
18e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
18e10 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
18e20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
18e30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18e40 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
18e50 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
18e60 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
18e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
18e80 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
18e90 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18ea0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18eb0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
18ec0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
18ed0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
18ee0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18ef0 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
18f00 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
18f10 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
18f20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18f30 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
18f40 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
18f50 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
18f60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18f70 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
18f80 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
18f90 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
18fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
18fb0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
18fc0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
18fd0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
18fe0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18ff0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
19000 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
19010 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
19020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
19030 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
19040 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
19050 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
19060 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19070 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
19080 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
19090 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
190a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
190b0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
190c0 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20  L_SPILL      26 
190d0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
190e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
190f0 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c  CONFIG_SMALL_MAL
19100 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20 2f  LOC        27  /
19110 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
19120 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19130 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a  IG_SORTERREF_SIZ
19140 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20 69 6e  E      28  /* in
19150 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
19160 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
19170 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 20 20  _MEMDB_MAXSIZE  
19180 20 20 20 20 20 32 39 20 20 2f 2a 20 73 71 6c 69       29  /* sqli
19190 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a 2f 2a  te3_int64 */../*
191a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
191b0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
191c0 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
191d0 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
191e0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
191f0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
19200 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
19210 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
19220 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
19230 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
19240 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
19250 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
19260 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
19270 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
19280 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
19290 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
192a0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
192b0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
192c0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
192d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
192e0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
192f0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
19300 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
19310 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
19320 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
19330 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
19340 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
19350 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
19360 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
19370 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
19380 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
19390 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
193a0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
193b0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
193c0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
193d0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
193e0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
193f0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
19400 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  l>.** [[SQLITE_D
19410 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
19420 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
19430 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
19440 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
19450 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
19460 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
19470 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
19480 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
19490 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
194a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
194b0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
194c0 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
194d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
194e0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
194f0 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
19500 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
19510 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
19520 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
19530 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
19540 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
19550 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
19560 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
19570 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
19580 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
19590 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
195a0 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
195b0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
195c0 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
195d0 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
195e0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
195f0 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
19600 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
19610 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
19620 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
19630 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
19640 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
19650 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
19660 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
19670 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
19680 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
19690 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
196a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
196b0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
196c0 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
196d0 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
196e0 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
196f0 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
19700 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
19710 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
19720 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
19730 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
19740 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
19750 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
19760 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
19770 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
19780 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
19790 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
197a0 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
197b0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
197c0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
197d0 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
197e0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
197f0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
19800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19810 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
19820 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
19830 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
19840 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
19850 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
19860 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
19870 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
19880 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
19890 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
198a0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
198b0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
198c0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
198d0 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
198e0 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
198f0 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
19900 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
19910 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
19920 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
19930 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
19940 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
19950 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
19960 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
19970 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
19980 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
19990 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46   [[SQLITE_DBCONF
199a0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 5d 5d  IG_ENABLE_FKEY]]
199b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
199c0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
199d0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
199e0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
199f0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
19a00 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
19a10 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
19a20 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
19a30 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
19a40 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
19a50 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
19a60 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
19a70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
19a80 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
19a90 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
19aa0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
19ab0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
19ac0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
19ad0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
19ae0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
19af0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
19b00 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
19b10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19b20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
19b30 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
19b40 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
19b50 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
19b60 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
19b70 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
19b80 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
19b90 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
19ba0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
19bb0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
19bc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
19bd0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
19be0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
19bf0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
19c00 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
19c10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
19c20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19c30 41 42 4c 45 5f 54 52 49 47 47 45 52 5d 5d 0a 2a  ABLE_TRIGGER]].*
19c40 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
19c50 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
19c60 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
19c70 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
19c80 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
19c90 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
19ca0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
19cb0 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
19cc0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
19cd0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
19ce0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
19cf0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
19d00 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
19d10 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
19d20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
19d30 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
19d40 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
19d50 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
19d60 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
19d70 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
19d80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
19d90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
19da0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
19db0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
19dc0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
19dd0 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
19de0 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
19df0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
19e00 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
19e10 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
19e20 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
19e30 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
19e40 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
19e50 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
19e60 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19e70 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
19e80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
19e90 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19ea0 45 5f 56 49 45 57 5d 5d 0a 2a 2a 20 3c 64 74 3e  E_VIEW]].** <dt>
19eb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19ec0 45 4e 41 42 4c 45 5f 56 49 45 57 3c 2f 64 74 3e  ENABLE_VIEW</dt>
19ed0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
19ee0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
19ef0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
19f00 6c 65 20 5b 43 52 45 41 54 45 20 56 49 45 57 20  le [CREATE VIEW 
19f10 7c 20 76 69 65 77 73 5d 2e 0a 2a 2a 20 54 68 65  | views]..** The
19f20 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
19f30 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
19f40 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
19f50 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
19f60 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
19f70 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
19f80 20 76 69 65 77 73 2c 0a 2a 2a 20 70 6f 73 69 74   views,.** posit
19f90 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 76 69  ive to enable vi
19fa0 65 77 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ews or negative 
19fb0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
19fc0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
19fd0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
19fe0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
19ff0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
1a000 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
1a010 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
1a020 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
1a030 68 65 74 68 65 72 20 76 69 65 77 73 20 61 72 65  hether views are
1a040 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
1a050 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
1a060 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
1a070 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a080 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
1a090 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
1a0a0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 76  which case the v
1a0b0 69 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  iew setting is n
1a0c0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
1a0d0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
1a0e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a0f0 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
1a100 4e 49 5a 45 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  NIZER]].** <dt>S
1a110 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a120 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e  NABLE_FTS3_TOKEN
1a130 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZER</dt>.** <dd
1a140 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
1a150 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
1a160 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 0a   or disable the.
1a170 2a 2a 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ** [fts3_tokeniz
1a180 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77  er()] function w
1a190 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20  hich is part of 
1a1a0 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75  the.** [FTS3] fu
1a1b0 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65  ll-text search e
1a1c0 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e  ngine extension.
1a1d0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
1a1e0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
1a1f0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
1a200 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1a210 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
1a220 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
1a230 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b  disable fts3_tok
1a240 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70  enizer() or.** p
1a250 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1a260 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
1a270 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  () or negative t
1a280 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
1a290 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ing.** unchanged
1a2a0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1a2b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1a2c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
1a2d0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
1a2e0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
1a2f0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
1a300 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f   whether fts3_to
1a310 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62  kenizer is disab
1a320 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
1a330 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
1a340 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
1a350 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
1a360 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
1a370 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
1a380 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
1a390 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
1a3a0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
1a3b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
1a3c0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1a3d0 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d  LOAD_EXTENSION]]
1a3e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
1a3f0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c  BCONFIG_ENABLE_L
1a400 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64  OAD_EXTENSION</d
1a410 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
1a420 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
1a430 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
1a440 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  able the [sqlite
1a450 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
1a460 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1a470 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f   independently o
1a480 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  f the [load_exte
1a490 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e  nsion()] SQL fun
1a4a0 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73  ction..** The [s
1a4b0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
1a4c0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
1a4d0 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  API enables or d
1a4e0 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65  isables both the
1a4f0 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74  .** C-API [sqlit
1a500 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
1a510 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c  n()] and the SQL
1a520 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f   function [load_
1a530 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a  extension()]..**
1a540 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
1a550 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1a560 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68  arguments..** Wh
1a570 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  en the first arg
1a580 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e  ument to this in
1a590 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 68  terface is 1, th
1a5a0 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50  en only the C-AP
1a5b0 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20  I is.** enabled 
1a5c0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
1a5d0 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73  tion remains dis
1a5e0 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66  abled.  If the f
1a5f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1a600 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61  .** this interfa
1a610 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f  ce is 0, then bo
1a620 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64  th the C-API and
1a630 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
1a640 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a  n are disabled..
1a650 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20  ** If the first 
1a660 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20  argument is -1, 
1a670 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20  then no changes 
1a680 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74  are made to stat
1a690 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a  e of either the.
1a6a0 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20  ** C-API or the 
1a6b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
1a6c0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1a6d0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
1a6e0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
1a6f0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
1a700 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
1a710 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
1a720 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  ther [sqlite3_lo
1a730 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
1a740 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
1a750 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
1a760 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  led following th
1a770 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
1a780 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
1a790 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20  ay.** be a NULL 
1a7a0 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63  pointer, in whic
1a7b0 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
1a7c0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
1a7d0 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  ported back..** 
1a7e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
1a7f0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
1a800 49 4e 44 42 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53  INDBNAME]] <dt>S
1a810 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d  QLITE_DBCONFIG_M
1a820 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a  AINDBNAME</dt>.*
1a830 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
1a840 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
1a850 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65 20 6f  hange the name o
1a860 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64 61 74  f the "main" dat
1a870 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e  abase.** schema.
1a880 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72 67 75    ^The sole argu
1a890 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
1a8a0 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20  r to a constant 
1a8b0 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77  UTF8 string.** w
1a8c0 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65  hich will become
1a8d0 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d 61 20   the new schema 
1a8e0 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  name in place of
1a8f0 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74   "main".  ^SQLit
1a900 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61  e.** does not ma
1a910 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ke a copy of the
1a920 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65 6d 61   new main schema
1a930 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f   name string, so
1a940 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1a950 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
1a960 74 68 61 74 20 74 68 65 20 61 72 67 75 6d 65 6e  that the argumen
1a970 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  t passed into th
1a980 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70 74 69  is DBCONFIG opti
1a990 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65 64 0a  on is unchanged.
1a9a0 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ** until after t
1a9b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a9c0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
1a9d0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
1a9e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a9f0 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
1aa00 5d 5d 20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  ]] .** <dt>SQLIT
1aa10 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b  E_DBCONFIG_NO_CK
1aa20 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e  PT_ON_CLOSE</dt>
1aa30 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79  .** <dd> Usually
1aa40 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  , when a databas
1aa50 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73  e in wal mode is
1aa60 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63   closed or detac
1aa70 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64  hed from a .** d
1aa80 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20  atabase handle, 
1aa90 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66  SQLite checks if
1aaa0 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20   this will mean 
1aab0 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20 6e  that there are n
1aac0 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63  ow no .** connec
1aad0 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20  tions at all to 
1aae0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49 66  the database. If
1aaf0 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73   so, it performs
1ab00 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a   a checkpoint .*
1ab10 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f  * operation befo
1ab20 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63  re closing the c
1ab30 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20  onnection. This 
1ab40 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73  option may be us
1ab50 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64  ed to.** overrid
1ab60 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75 72  e this behaviour
1ab70 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  . The first para
1ab80 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
1ab90 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a  this operation.*
1aba0 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  * is an integer 
1abb0 2d 20 70 6f 73 69 74 69 76 65 20 74 6f 20 64 69  - positive to di
1abc0 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74  sable checkpoint
1abd0 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a  s-on-close, or z
1abe0 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61  ero (the.** defa
1abf0 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74  ult) to enable t
1ac00 68 65 6d 2c 20 61 6e 64 20 6e 65 67 61 74 69 76  hem, and negativ
1ac10 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
1ac20 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
1ac30 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1ac40 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1ac50 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
1ac60 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69  eger.** into whi
1ac70 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ch is written 0 
1ac80 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
1ac90 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f   whether checkpo
1aca0 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a  ints-on-close.**
1acb0 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61 62   have been disab
1acc0 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79 20  led - 0 if they 
1acd0 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64  are not disabled
1ace0 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65 2e  , 1 if they are.
1acf0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1ad00 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
1ad10 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 5d 5d 20  G_ENABLE_QPSG]] 
1ad20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1ad30 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c  FIG_ENABLE_QPSG<
1ad40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  /dt>.** <dd>^(Th
1ad50 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1ad60 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70  G_ENABLE_QPSG op
1ad70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f  tion activates o
1ad80 72 20 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a  r deactivates.**
1ad90 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e   the [query plan
1ada0 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20 67 75  ner stability gu
1adb0 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e  arantee] (QPSG).
1adc0 20 20 57 68 65 6e 20 74 68 65 20 51 50 53 47 20    When the QPSG 
1add0 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20  is active,.** a 
1ade0 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79  single SQL query
1adf0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
1ae00 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73  always use the s
1ae10 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65  ame algorithm re
1ae20 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76  gardless.** of v
1ae30 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20  alues of [bound 
1ae40 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54  parameters].)^ T
1ae50 68 65 20 51 50 53 47 20 64 69 73 61 62 6c 65 73  he QPSG disables
1ae60 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69   some query opti
1ae70 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61  mizations.** tha
1ae80 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61  t look at the va
1ae90 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61  lues of bound pa
1aea0 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20  rameters, which 
1aeb0 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75  can make some qu
1aec0 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e  eries.** slower.
1aed0 20 20 42 75 74 20 74 68 65 20 51 50 53 47 20 68    But the QPSG h
1aee0 61 73 20 74 68 65 20 61 64 76 61 6e 74 61 67 65  as the advantage
1aef0 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74   of more predict
1af00 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20  able behavior.  
1af10 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47  With.** the QPSG
1af20 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20   active, SQLite 
1af30 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20  will always use 
1af40 74 68 65 20 73 61 6d 65 20 71 75 65 72 79 20 70  the same query p
1af50 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64  lan in the field
1af60 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20   as.** was used 
1af70 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69  during testing i
1af80 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68  n the lab..** Th
1af90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1afa0 20 74 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67   to this setting
1afb0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
1afc0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
1afd0 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20 51 50 53  able .** the QPS
1afe0 47 2c 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  G, positive to e
1aff0 6e 61 62 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e  nable QPSG, or n
1b000 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
1b010 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
1b020 75 6e 63 68 61 6e 67 65 64 2e 20 54 68 65 20 73  unchanged. The s
1b030 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1b040 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1b050 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
1b060 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
1b070 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
1b080 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
1b090 68 65 20 51 50 53 47 20 69 73 20 64 69 73 61 62  he QPSG is disab
1b0a0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
1b0b0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
1b0c0 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   call..** </dd>.
1b0d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  **.** [[SQLITE_D
1b0e0 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f  BCONFIG_TRIGGER_
1b0f0 45 51 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EQP]] <dt>SQLITE
1b100 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45  _DBCONFIG_TRIGGE
1b110 52 5f 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  R_EQP</dt>.** <d
1b120 64 3e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  d> By default, t
1b130 68 65 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50  he output of EXP
1b140 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20  LAIN QUERY PLAN 
1b150 63 6f 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f  commands does no
1b160 74 20 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75  t .** include ou
1b170 74 70 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65  tput for any ope
1b180 72 61 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65  rations performe
1b190 64 20 62 79 20 74 72 69 67 67 65 72 20 70 72 6f  d by trigger pro
1b1a0 67 72 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f  grams. This.** o
1b1b0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
1b1c0 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74   set or clear (t
1b1d0 68 65 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c  he default) a fl
1b1e0 61 67 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20  ag that governs 
1b1f0 74 68 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72  this.** behavior
1b200 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  . The first para
1b210 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
1b220 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69  this operation i
1b230 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a  s an integer -.*
1b240 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
1b250 61 62 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20  able output for 
1b260 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
1b270 2c 20 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73  , or zero to dis
1b280 61 62 6c 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e  able it,.** or n
1b290 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
1b2a0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
1b2b0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
1b2c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1b2d0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1b2e0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
1b2f0 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e  which is written
1b300 20 0a 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20 69   .** 0 or 1 to i
1b310 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
1b320 6f 75 74 70 75 74 2d 66 6f 72 2d 74 72 69 67 67  output-for-trigg
1b330 65 72 73 20 68 61 73 20 62 65 65 6e 20 64 69 73  ers has been dis
1b340 61 62 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a  abled - 0 if .**
1b350 20 69 74 20 69 73 20 6e 6f 74 20 64 69 73 61 62   it is not disab
1b360 6c 65 64 2c 20 31 20 69 66 20 69 74 20 69 73 2e  led, 1 if it is.
1b370 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a    .** </dd>.**.*
1b380 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1b390 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41  FIG_RESET_DATABA
1b3a0 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  SE]] <dt>SQLITE_
1b3b0 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44  DBCONFIG_RESET_D
1b3c0 41 54 41 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20  ATABASE</dt>.** 
1b3d0 3c 64 64 3e 20 53 65 74 20 74 68 65 20 53 51 4c  <dd> Set the SQL
1b3e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1b3f0 45 54 5f 44 41 54 41 42 41 53 45 20 66 6c 61 67  ET_DATABASE flag
1b400 20 61 6e 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a   and then run.**
1b410 20 5b 56 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64   [VACUUM] in ord
1b420 65 72 20 74 6f 20 72 65 73 65 74 20 61 20 64 61  er to reset a da
1b430 74 61 62 61 73 65 20 62 61 63 6b 20 74 6f 20 61  tabase back to a
1b440 6e 20 65 6d 70 74 79 20 64 61 74 61 62 61 73 65  n empty database
1b450 0a 2a 2a 20 77 69 74 68 20 6e 6f 20 73 63 68 65  .** with no sche
1b460 6d 61 20 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e  ma and no conten
1b470 74 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  t. The following
1b480 20 70 72 6f 63 65 73 73 20 77 6f 72 6b 73 20 65   process works e
1b490 76 65 6e 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64  ven for.** a bad
1b4a0 6c 79 20 63 6f 72 72 75 70 74 65 64 20 64 61 74  ly corrupted dat
1b4b0 61 62 61 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c  abase file:.** <
1b4c0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74  ol>.** <li> If t
1b4d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1b4e0 65 63 74 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20  ection is newly 
1b4f0 6f 70 65 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72  opened, make sur
1b500 65 20 69 74 20 68 61 73 20 72 65 61 64 20 74 68  e it has read th
1b510 65 0a 2a 2a 20 20 20 20 20 20 64 61 74 61 62 61  e.**      databa
1b520 73 65 20 73 63 68 65 6d 61 20 62 79 20 70 72 65  se schema by pre
1b530 70 61 72 69 6e 67 20 74 68 65 6e 20 64 69 73 63  paring then disc
1b540 61 72 64 69 6e 67 20 73 6f 6d 65 20 71 75 65 72  arding some quer
1b550 79 20 61 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a  y against the.**
1b560 20 20 20 20 20 20 64 61 74 61 62 61 73 65 2c 20        database, 
1b570 6f 72 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  or calling sqlit
1b580 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
1b590 6d 65 74 61 64 61 74 61 28 29 2c 20 69 67 6e 6f  metadata(), igno
1b5a0 72 69 6e 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20  ring any.**     
1b5b0 20 65 72 72 6f 72 73 2e 20 20 54 68 69 73 20 73   errors.  This s
1b5c0 74 65 70 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65  tep is only nece
1b5d0 73 73 61 72 79 20 69 66 20 74 68 65 20 61 70 70  ssary if the app
1b5e0 6c 69 63 61 74 69 6f 6e 20 64 65 73 69 72 65 73  lication desires
1b5f0 20 74 6f 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20   to keep.**     
1b600 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
1b610 20 57 41 4c 20 6d 6f 64 65 20 61 66 74 65 72 20   WAL mode after 
1b620 74 68 65 20 72 65 73 65 74 20 69 66 20 69 74 20  the reset if it 
1b630 77 61 73 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20  was in WAL mode 
1b640 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74  before.**      t
1b650 68 65 20 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c  he reset.  .** <
1b660 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  li> sqlite3_db_c
1b670 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 54 45  onfig(db, SQLITE
1b680 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1b690 44 41 54 41 42 41 53 45 2c 20 31 2c 20 30 29 3b  DATABASE, 1, 0);
1b6a0 0a 2a 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  .** <li> [sqlite
1b6b0 33 5f 65 78 65 63 5d 28 64 62 2c 20 22 5b 56 41  3_exec](db, "[VA
1b6c0 43 55 55 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29  CUUM]", 0, 0, 0)
1b6d0 3b 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  ;.** <li> sqlite
1b6e0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20  3_db_config(db, 
1b6f0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b700 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c 20  RESET_DATABASE, 
1b710 30 2c 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  0, 0);.** </ol>.
1b720 2a 2a 20 42 65 63 61 75 73 65 20 72 65 73 65 74  ** Because reset
1b730 74 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  ting a database 
1b740 69 73 20 64 65 73 74 72 75 63 74 69 76 65 20 61  is destructive a
1b750 6e 64 20 69 72 72 65 76 65 72 73 69 62 6c 65 2c  nd irreversible,
1b760 20 74 68 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20   the.** process 
1b770 72 65 71 75 69 72 65 73 20 74 68 65 20 75 73 65  requires the use
1b780 20 6f 66 20 74 68 69 73 20 6f 62 73 63 75 72 65   of this obscure
1b790 20 41 50 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c   API and multipl
1b7a0 65 20 73 74 65 70 73 20 74 6f 20 68 65 6c 70 0a  e steps to help.
1b7b0 2a 2a 20 65 6e 73 75 72 65 20 74 68 61 74 20 69  ** ensure that i
1b7c0 74 20 64 6f 65 73 20 6e 6f 74 20 68 61 70 70 65  t does not happe
1b7d0 6e 20 62 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a  n by accident..*
1b7e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42  *.** [[SQLITE_DB
1b7f0 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49 56 45  CONFIG_DEFENSIVE
1b800 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ]] <dt>SQLITE_DB
1b810 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49 56 45  CONFIG_DEFENSIVE
1b820 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b830 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1b840 5f 44 45 46 45 4e 53 49 56 45 20 6f 70 74 69 6f  _DEFENSIVE optio
1b850 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
1b860 65 61 63 74 69 76 61 74 65 73 20 74 68 65 0a 2a  eactivates the.*
1b870 2a 20 22 64 65 66 65 6e 73 69 76 65 22 20 66 6c  * "defensive" fl
1b880 61 67 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  ag for a databas
1b890 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 57  e connection.  W
1b8a0 68 65 6e 20 74 68 65 20 64 65 66 65 6e 73 69 76  hen the defensiv
1b8b0 65 0a 2a 2a 20 66 6c 61 67 20 69 73 20 65 6e 61  e.** flag is ena
1b8c0 62 6c 65 64 2c 20 6c 61 6e 67 75 61 67 65 20 66  bled, language f
1b8d0 65 61 74 75 72 65 73 20 74 68 61 74 20 61 6c 6c  eatures that all
1b8e0 6f 77 20 6f 72 64 69 6e 61 72 79 20 53 51 4c 20  ow ordinary SQL 
1b8f0 74 6f 20 0a 2a 2a 20 64 65 6c 69 62 65 72 61 74  to .** deliberat
1b900 65 6c 79 20 63 6f 72 72 75 70 74 20 74 68 65 20  ely corrupt the 
1b910 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 72  database file ar
1b920 65 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65  e disabled.  The
1b930 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 65 61   disabled.** fea
1b940 74 75 72 65 73 20 69 6e 63 6c 75 64 65 20 62 75  tures include bu
1b950 74 20 61 72 65 20 6e 6f 74 20 6c 69 6d 69 74 65  t are not limite
1b960 64 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69  d to the followi
1b970 6e 67 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ng:.** <ul>.** <
1b980 6c 69 3e 20 54 68 65 20 5b 50 52 41 47 4d 41 20  li> The [PRAGMA 
1b990 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d  writable_schema=
1b9a0 4f 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  ON] statement..*
1b9b0 2a 20 3c 6c 69 3e 20 54 68 65 20 5b 50 52 41 47  * <li> The [PRAG
1b9c0 4d 41 20 6a 6f 75 72 6e 61 6c 5f 6d 6f 64 65 3d  MA journal_mode=
1b9d0 4f 46 46 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  OFF] statement..
1b9e0 2a 2a 20 3c 6c 69 3e 20 57 72 69 74 65 73 20 74  ** <li> Writes t
1b9f0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 5f 64 62  o the [sqlite_db
1ba00 70 61 67 65 5d 20 76 69 72 74 75 61 6c 20 74 61  page] virtual ta
1ba10 62 6c 65 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 69 72  ble..** <li> Dir
1ba20 65 63 74 20 77 72 69 74 65 73 20 74 6f 20 5b 73  ect writes to [s
1ba30 68 61 64 6f 77 20 74 61 62 6c 65 73 5d 2e 0a 2a  hadow tables]..*
1ba40 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e  * </ul>.** </dd>
1ba50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
1ba60 44 42 43 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c  DBCONFIG_WRITABL
1ba70 45 5f 53 43 48 45 4d 41 5d 5d 20 3c 64 74 3e 53  E_SCHEMA]] <dt>S
1ba80 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57  QLITE_DBCONFIG_W
1ba90 52 49 54 41 42 4c 45 5f 53 43 48 45 4d 41 3c 2f  RITABLE_SCHEMA</
1baa0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53  dt>.** <dd>The S
1bab0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57  QLITE_DBCONFIG_W
1bac0 52 49 54 41 42 4c 45 5f 53 43 48 45 4d 41 20 6f  RITABLE_SCHEMA o
1bad0 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20  ption activates 
1bae0 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 20 74  or deactivates t
1baf0 68 65 0a 2a 2a 20 22 77 72 69 74 61 62 6c 65 5f  he.** "writable_
1bb00 73 63 68 65 6d 61 22 20 66 6c 61 67 2e 20 54 68  schema" flag. Th
1bb10 69 73 20 68 61 73 20 74 68 65 20 73 61 6d 65 20  is has the same 
1bb20 65 66 66 65 63 74 20 61 6e 64 20 69 73 20 6c 6f  effect and is lo
1bb30 67 69 63 61 6c 6c 79 20 65 71 75 69 76 61 6c 65  gically equivale
1bb40 6e 74 0a 2a 2a 20 74 6f 20 73 65 74 74 69 6e 67  nt.** to setting
1bb50 20 5b 50 52 41 47 4d 41 20 77 72 69 74 61 62 6c   [PRAGMA writabl
1bb60 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d 20 6f 72 20  e_schema=ON] or 
1bb70 5b 50 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65  [PRAGMA writable
1bb80 5f 73 63 68 65 6d 61 3d 4f 46 46 5d 2e 0a 2a 2a  _schema=OFF]..**
1bb90 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1bba0 65 6e 74 20 74 6f 20 74 68 69 73 20 73 65 74 74  ent to this sett
1bbb0 69 6e 67 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ing is an intege
1bbc0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
1bbd0 64 69 73 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20  disable .** the 
1bbe0 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 2c  writable_schema,
1bbf0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
1bc00 62 6c 65 20 77 72 69 74 61 62 6c 65 5f 73 63 68  ble writable_sch
1bc10 65 6d 61 2c 20 6f 72 20 6e 65 67 61 74 69 76 65  ema, or negative
1bc20 20 74 6f 0a 2a 2a 20 6c 65 61 76 65 20 74 68 65   to.** leave the
1bc30 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
1bc40 65 64 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  ed. The second p
1bc50 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
1bc60 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
1bc70 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
1bc80 68 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  h is written 0 o
1bc90 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
1bca0 77 68 65 74 68 65 72 20 74 68 65 20 77 72 69 74  whether the writ
1bcb0 61 62 6c 65 5f 73 63 68 65 6d 61 0a 2a 2a 20 69  able_schema.** i
1bcc0 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
1bcd0 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  abled following 
1bce0 74 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f  this call..** </
1bcf0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
1bd00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 45 47 41  TE_DBCONFIG_LEGA
1bd10 43 59 5f 41 4c 54 45 52 5f 54 41 42 4c 45 5d 5d  CY_ALTER_TABLE]]
1bd20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
1bd30 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41  BCONFIG_LEGACY_A
1bd40 4c 54 45 52 5f 54 41 42 4c 45 3c 2f 64 74 3e 0a  LTER_TABLE</dt>.
1bd50 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
1bd60 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43  E_DBCONFIG_LEGAC
1bd70 59 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 6f 70  Y_ALTER_TABLE op
1bd80 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f  tion activates o
1bd90 72 20 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a  r deactivates.**
1bda0 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
1bdb0 76 69 6f 72 20 6f 66 20 74 68 65 20 5b 41 4c 54  vior of the [ALT
1bdc0 45 52 20 54 41 42 4c 45 20 52 45 4e 41 4d 45 5d  ER TABLE RENAME]
1bdd0 20 63 6f 6d 6d 61 6e 64 20 73 75 63 68 20 69 74   command such it
1bde0 0a 2a 2a 20 62 65 68 61 76 65 73 20 61 73 20 69  .** behaves as i
1bdf0 74 20 64 69 64 20 70 72 69 6f 72 20 74 6f 20 5b  t did prior to [
1be00 76 65 72 73 69 6f 6e 20 33 2e 32 34 2e 30 5d 20  version 3.24.0] 
1be10 28 32 30 31 38 2d 30 36 2d 30 34 29 2e 20 20 53  (2018-06-04).  S
1be20 65 65 20 74 68 65 0a 2a 2a 20 22 43 6f 6d 70 61  ee the.** "Compa
1be30 74 69 62 69 6c 69 74 79 20 4e 6f 74 69 63 65 22  tibility Notice"
1be40 20 6f 6e 20 74 68 65 20 5b 41 4c 54 45 52 20 54   on the [ALTER T
1be50 41 42 4c 45 20 52 45 4e 41 4d 45 20 64 6f 63 75  ABLE RENAME docu
1be60 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a  mentation] for.*
1be70 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
1be80 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 69 73 20 66  ormation. This f
1be90 65 61 74 75 72 65 20 63 61 6e 20 61 6c 73 6f 20  eature can also 
1bea0 62 65 20 74 75 72 6e 65 64 20 6f 6e 20 61 6e 64  be turned on and
1beb0 20 6f 66 66 0a 2a 2a 20 75 73 69 6e 67 20 74 68   off.** using th
1bec0 65 20 5b 50 52 41 47 4d 41 20 6c 65 67 61 63 79  e [PRAGMA legacy
1bed0 5f 61 6c 74 65 72 5f 74 61 62 6c 65 5d 20 73 74  _alter_table] st
1bee0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 2f 64 64  atement..** </dd
1bef0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
1bf00 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 4d  _DBCONFIG_DQS_DM
1bf10 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  L]].** <dt>SQLIT
1bf20 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44  E_DBCONFIG_DQS_D
1bf30 4d 4c 3c 2f 74 64 3e 0a 2a 2a 20 3c 64 64 3e 54  ML</td>.** <dd>T
1bf40 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
1bf50 49 47 5f 44 51 53 5f 44 4d 4c 20 6f 70 74 69 6f  IG_DQS_DML optio
1bf60 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
1bf70 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68  eactivates.** th
1bf80 65 20 6c 65 67 61 63 79 20 5b 64 6f 75 62 6c 65  e legacy [double
1bf90 2d 71 75 6f 74 65 64 20 73 74 72 69 6e 67 20 6c  -quoted string l
1bfa0 69 74 65 72 61 6c 5d 20 6d 69 73 66 65 61 74 75  iteral] misfeatu
1bfb0 72 65 20 66 6f 72 20 44 4d 4c 20 73 74 61 74 65  re for DML state
1bfc0 6d 65 6e 74 0a 2a 2a 20 6f 6e 6c 79 2c 20 74 68  ment.** only, th
1bfd0 61 74 20 69 73 20 44 45 4c 45 54 45 2c 20 49 4e  at is DELETE, IN
1bfe0 53 45 52 54 2c 20 53 45 4c 45 43 54 2c 20 61 6e  SERT, SELECT, an
1bff0 64 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  d UPDATE stateme
1c000 6e 74 73 2e 20 54 68 65 0a 2a 2a 20 64 65 66 61  nts. The.** defa
1c010 75 6c 74 20 76 61 6c 75 65 20 6f 66 20 74 68 69  ult value of thi
1c020 73 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  s setting is det
1c030 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b  ermined by the [
1c040 2d 44 53 51 4c 49 54 45 5f 44 51 53 5d 0a 2a 2a  -DSQLITE_DQS].**
1c050 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1c060 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tion..** </dd>.*
1c070 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42  *.** [[SQLITE_DB
1c080 43 4f 4e 46 49 47 5f 44 51 53 5f 44 44 4c 5d 5d  CONFIG_DQS_DDL]]
1c090 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
1c0a0 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 44 4c 3c  BCONFIG_DQS_DDL<
1c0b0 2f 74 64 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /td>.** <dd>The 
1c0c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1c0d0 44 51 53 20 6f 70 74 69 6f 6e 20 61 63 74 69 76  DQS option activ
1c0e0 61 74 65 73 20 6f 72 20 64 65 61 63 74 69 76 61  ates or deactiva
1c0f0 74 65 73 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63  tes.** the legac
1c100 79 20 5b 64 6f 75 62 6c 65 2d 71 75 6f 74 65 64  y [double-quoted
1c110 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 5d   string literal]
1c120 20 6d 69 73 66 65 61 74 75 72 65 20 66 6f 72 20   misfeature for 
1c130 44 44 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a  DDL statements,.
1c140 2a 2a 20 73 75 63 68 20 61 73 20 43 52 45 41 54  ** such as CREAT
1c150 45 20 54 41 42 4c 45 20 61 6e 64 20 43 52 45 41  E TABLE and CREA
1c160 54 45 20 49 4e 44 45 58 2e 20 54 68 65 0a 2a 2a  TE INDEX. The.**
1c170 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f   default value o
1c180 66 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  f this setting i
1c190 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  s determined by 
1c1a0 74 68 65 20 5b 2d 44 53 51 4c 49 54 45 5f 44 51  the [-DSQLITE_DQ
1c1b0 53 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  S].** compile-ti
1c1c0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f  me option..** </
1c1d0 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
1c1e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c1f0 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41  BCONFIG_MAINDBNA
1c200 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31 30  ME            10
1c210 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72  00 /* const char
1c220 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1c230 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
1c240 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20  KASIDE          
1c250 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a     1001 /* void*
1c260 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
1c270 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1c280 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
1c290 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f            1002 /
1c2a0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1c2b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1c2c0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
1c2d0 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33  GGER        1003
1c2e0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1c2f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c300 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
1c310 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30  TS3_TOKENIZER 10
1c320 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  04 /* int int* *
1c330 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c340 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1c350 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
1c360 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1005 /* int int*
1c370 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c380 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
1c390 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20  KPT_ON_CLOSE    
1c3a0 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e    1006 /* int in
1c3b0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1c3c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1c3d0 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20 20 20  ABLE_QPSG       
1c3e0 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e 74 20      1007 /* int 
1c3f0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1c400 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1c410 54 52 49 47 47 45 52 5f 45 51 50 20 20 20 20 20  TRIGGER_EQP     
1c420 20 20 20 20 20 20 31 30 30 38 20 2f 2a 20 69 6e        1008 /* in
1c430 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1c440 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1c450 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45  G_RESET_DATABASE
1c460 20 20 20 20 20 20 20 20 31 30 30 39 20 2f 2a 20          1009 /* 
1c470 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1c480 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1c490 46 49 47 5f 44 45 46 45 4e 53 49 56 45 20 20 20  FIG_DEFENSIVE   
1c4a0 20 20 20 20 20 20 20 20 20 20 31 30 31 30 20 2f            1010 /
1c4b0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1c4c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1c4d0 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53  ONFIG_WRITABLE_S
1c4e0 43 48 45 4d 41 20 20 20 20 20 20 20 31 30 31 31  CHEMA       1011
1c4f0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1c500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c510 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41  BCONFIG_LEGACY_A
1c520 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 31 30  LTER_TABLE    10
1c530 31 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  12 /* int int* *
1c540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c550 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 4d  _DBCONFIG_DQS_DM
1c560 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  L               
1c570 31 30 31 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1013 /* int int*
1c580 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c590 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f  TE_DBCONFIG_DQS_
1c5a0 44 44 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  DDL             
1c5b0 20 20 31 30 31 34 20 2f 2a 20 69 6e 74 20 69 6e    1014 /* int in
1c5c0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1c5d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1c5e0 41 42 4c 45 5f 56 49 45 57 20 20 20 20 20 20 20  ABLE_VIEW       
1c5f0 20 20 20 20 31 30 31 35 20 2f 2a 20 69 6e 74 20      1015 /* int 
1c600 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1c610 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1c620 4d 41 58 20 20 20 20 20 20 20 20 20 20 20 20 20  MAX             
1c630 20 20 20 20 20 20 31 30 31 35 20 2f 2a 20 4c 61        1015 /* La
1c640 72 67 65 73 74 20 44 42 43 4f 4e 46 49 47 20 2a  rgest DBCONFIG *
1c650 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1c660 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
1c670 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
1c680 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45  sult Codes.** ME
1c690 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1c6a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c6b0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
1c6c0 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
1c6d0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
1c6e0 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
1c6f0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1c700 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
1c710 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
1c720 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
1c730 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
1c740 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
1c750 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
1c760 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e  atibility..*/.in
1c770 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
1c780 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
1c790 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
1c7a0 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
1c7b0 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
1c7c0 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48  rt Rowid.** METH
1c7d0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c7e0 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
1c7f0 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62   most SQLite tab
1c800 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20  les (except for 
1c810 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
1c820 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61  tables).** has a
1c830 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
1c840 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
1c850 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
1c860 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
1c870 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
1c880 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
1c890 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
1c8a0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
1c8b0 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
1c8c0 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
1c8d0 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
1c8e0 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
1c8f0 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
1c900 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
1c910 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
1c920 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
1c930 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
1c940 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
1c950 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
1c960 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
1c970 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
1c980 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  owid..**.** ^The
1c990 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1c9a0 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e  sert_rowid(D) in
1c9b0 74 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20  terface usually 
1c9c0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
1c9d0 69 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f  id] of.** the mo
1c9e0 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
1c9f0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
1ca00 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
1ca10 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
1ca20 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
1ca30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
1ca40 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
1ca50 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
1ca60 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ables are not.**
1ca70 20 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e   recorded. ^If n
1ca80 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
1ca90 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
1caa0 64 20 74 61 62 6c 65 73 20 68 61 76 65 20 65 76  d tables have ev
1cab0 65 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20  er occurred .** 
1cac0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
1cad0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68  connection D, th
1cae0 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  en sqlite3_last_
1caf0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
1cb00 72 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f  returns .** zero
1cb10 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20  ..**.** As well 
1cb20 61 73 20 62 65 69 6e 67 20 73 65 74 20 61 75 74  as being set aut
1cb30 6f 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f  omatically as ro
1cb40 77 73 20 61 72 65 20 69 6e 73 65 72 74 65 64 20  ws are inserted 
1cb50 69 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a  into database.**
1cb60 20 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c   tables, the val
1cb70 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
1cb80 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
1cb90 20 62 65 20 73 65 74 20 65 78 70 6c 69 63 69 74   be set explicit
1cba0 6c 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ly by.** [sqlite
1cbb0 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1cbc0 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a  t_rowid()].**.**
1cbd0 20 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61   Some virtual ta
1cbe0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
1cbf0 6f 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72  ons may INSERT r
1cc00 6f 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  ows into rowid t
1cc10 61 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74  ables as.** part
1cc20 20 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61   of committing a
1cc30 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e   transaction (e.
1cc40 67 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  g. to flush data
1cc50 20 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20   accumulated in 
1cc60 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73  memory.** to dis
1cc70 6b 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  k). In this case
1cc80 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1cc90 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
1cca0 6f 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f  on return the ro
1ccb0 77 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  wid.** associate
1ccc0 64 20 77 69 74 68 20 74 68 65 73 65 20 69 6e 74  d with these int
1ccd0 65 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65  ernal INSERT ope
1cce0 72 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c  rations, which l
1ccf0 65 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e  eads to .** unin
1cd00 74 75 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e  tuitive results.
1cd10 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
1cd20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
1cd30 68 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20  hat do write to 
1cd40 72 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20  rowid.** tables 
1cd50 69 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e 20  in this way can 
1cd60 61 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c  avoid this probl
1cd70 65 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20  em by restoring 
1cd80 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a  the original .**
1cd90 20 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69   rowid value usi
1cda0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ng [sqlite3_set_
1cdb0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1cdc0 64 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75  d()] before retu
1cdd0 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f  rning .** contro
1cde0 6c 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a  l to the user..*
1cdf0 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
1ce00 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
1ce10 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 74 68  hin a trigger th
1ce20 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
1ce30 77 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20  will .** return 
1ce40 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
1ce50 68 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20  he inserted row 
1ce60 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
1ce70 72 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75  rigger is .** ru
1ce80 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20  nning. Once the 
1ce90 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1cea0 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
1ceb0 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
1cec0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
1ced0 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
1cee0 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
1cef0 72 69 67 67 65 72 20 77 61 73 20 66 69 72 65 64  rigger was fired
1cf00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
1cf10 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
1cf20 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
1cf30 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
1cf40 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
1cf50 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
1cf60 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
1cf70 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
1cf80 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
1cf90 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
1cfa0 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
1cfb0 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
1cfc0 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
1cfd0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
1cfe0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
1cff0 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
1d000 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
1d010 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
1d020 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
1d030 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
1d040 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
1d050 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
1d060 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
1d070 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
1d080 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
1d090 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
1d0a0 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
1d0b0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
1d0c0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
1d0d0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
1d0e0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
1d0f0 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
1d100 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
1d110 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
1d120 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1d130 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1d140 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
1d150 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
1d160 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
1d170 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
1d180 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
1d190 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
1d1a0 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
1d1b0 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
1d1c0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
1d1d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
1d1e0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
1d1f0 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
1d200 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
1d210 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
1d220 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1d230 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1d240 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
1d250 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
1d260 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
1d270 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
1d280 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
1d290 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1d2a0 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
1d2b0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
1d2c0 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
1d2d0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
1d2e0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
1d2f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1d300 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
1d310 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1d320 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
1d330 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
1d340 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
1d350 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
1d360 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
1d370 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
1d380 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1d390 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1d3a0 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
1d3b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d3c0 45 46 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74  EF: Set the Last
1d3d0 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61   Insert Rowid va
1d3e0 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lue..** METHOD: 
1d3f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1d400 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61  e sqlite3_set_la
1d410 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1d420 44 2c 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c  D, R) method all
1d430 6f 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74  ows the applicat
1d440 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68  ion to.** set th
1d450 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1d460 20 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   by calling sqli
1d470 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1d480 72 6f 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a  rowid(D) to R .*
1d490 2a 20 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74  * without insert
1d4a0 69 6e 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74  ing a row into t
1d4b0 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a  he database..*/.
1d4c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
1d4d0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1d4e0 69 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69  id(sqlite3*,sqli
1d4f0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  te3_int64);../*.
1d500 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
1d510 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
1d520 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
1d530 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1d540 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
1d550 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1d560 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1d570 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
1d580 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  rted or.** delet
1d590 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
1d5a0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
1d5b0 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
1d5c0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
1d5d0 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64  atement on the d
1d5e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d5f0 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
1d600 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
1d610 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e  er..** ^Executin
1d620 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
1d630 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1d640 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66  t does not modif
1d650 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  y the value.** r
1d660 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
1d670 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
1d680 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61  ^Only changes ma
1d690 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74  de directly by t
1d6a0 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
1d6b0 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
1d6c0 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e  ement are.** con
1d6d0 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69  sidered - auxili
1d6e0 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
1d6f0 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52  ed by [CREATE TR
1d700 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
1d710 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20  ], .** [foreign 
1d720 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20  key actions] or 
1d730 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
1d740 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
1d750 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1d760 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20  .** .** Changes 
1d770 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
1d780 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
1d790 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f  y .** [INSTEAD O
1d7a0 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54  F trigger | INST
1d7b0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d  EAD OF triggers]
1d7c0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1d7d0 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a  . ^The value .**
1d7e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1d7f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
1d800 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
1d810 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1d820 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45  TE or .** DELETE
1d830 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f   statement run o
1d840 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61  n a view is alwa
1d850 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68  ys zero. Only ch
1d860 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65  anges made to re
1d870 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72  al .** tables ar
1d880 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
1d890 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65   Things are more
1d8a0 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20   complicated if 
1d8b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
1d8c0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
1d8d0 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68  s.** executed wh
1d8e0 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72  ile a trigger pr
1d8f0 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67  ogram is running
1d900 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65  . This may happe
1d910 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67  n if the.** prog
1d920 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68  ram uses the [ch
1d930 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1d940 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d  tion], or if som
1d950 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b  e other callback
1d960 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76  .** function inv
1d970 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61  okes sqlite3_cha
1d980 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e  nges() directly.
1d990 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a   Essentially:.**
1d9a0 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c   .** <ul>.**   <
1d9b0 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74  li> ^(Before ent
1d9c0 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20  ering a trigger 
1d9d0 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75  program the valu
1d9e0 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
1d9f0 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
1da00 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
1da10 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74  on is saved. Aft
1da20 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70  er the trigger p
1da30 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20  rogram .**      
1da40 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20    has finished, 
1da50 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c  the original val
1da60 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29  ue is restored.)
1da70 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ^.** .**   <li> 
1da80 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67  ^(Within a trigg
1da90 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20  er program each 
1daa0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61  INSERT, UPDATE a
1dab0 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20  nd DELETE .**   
1dac0 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73       statement s
1dad0 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65  ets the value re
1dae0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1daf0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1db00 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70         upon comp
1db10 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c  letion as normal
1db20 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69  . Of course, thi
1db30 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74  s value will not
1db40 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20   include .**    
1db50 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20      any changes 
1db60 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62  performed by sub
1db70 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68  -triggers, as th
1db80 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1db90 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76  s() .**        v
1dba0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76  alue will be sav
1dbb0 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20  ed and restored 
1dbc0 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74  after each sub-t
1dbd0 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29  rigger has run.)
1dbe0 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ^.** </ul>.** .*
1dbf0 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68  * ^This means th
1dc00 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65  at if the change
1dc10 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1dc20 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73   (or similar) is
1dc30 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
1dc40 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50  first INSERT, UP
1dc50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1dc60 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1dc70 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a  a trigger, it .*
1dc80 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  * returns the va
1dc90 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20  lue as set when 
1dca0 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74  the calling stat
1dcb0 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63  ement began exec
1dcc0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74  uting..** ^If it
1dcd0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1dce0 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71  second or subseq
1dcf0 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d  uent such statem
1dd00 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1dd10 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d  gger .** program
1dd20 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1dd30 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68  rned reflects th
1dd40 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1dd50 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65   modified by the
1dd60 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e   .** previous IN
1dd70 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1dd80 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1dd90 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
1dda0 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
1ddb0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1ddc0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1ddd0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1dde0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ddf0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1de00 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1de10 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1de20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1de30 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
1de40 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
1de50 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a  eaningful..**.**
1de60 20 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75   See also:.** <u
1de70 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  l>.** <li> the [
1de80 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1de90 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1dea0 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  ce.** <li> the [
1deb0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1dec0 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68  agma].** <li> th
1ded0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1dee0 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c   function].** <l
1def0 69 3e 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72  i> the [data_ver
1df00 73 69 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20  sion pragma].** 
1df10 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  </ul>.*/.int sql
1df20 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
1df30 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1df40 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
1df50 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1df60 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1df70 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1df80 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1df90 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
1dfa0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1dfb0 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
1dfc0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1dfd0 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
1dfe0 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
1dff0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
1e000 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
1e010 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
1e020 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
1e030 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
1e040 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
1e050 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
1e060 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
1e070 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
1e080 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1e090 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1e0a0 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
1e0b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1e0c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
1e0d0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
1e0e0 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
1e0f0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
1e100 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1e110 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
1e120 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
1e130 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
1e140 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
1e150 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
1e160 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
1e170 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
1e180 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
1e190 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
1e1a0 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
1e1b0 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
1e1c0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  t counted..**.**
1e1d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   The [sqlite3_to
1e1e0 74 61 6c 5f 63 68 61 6e 67 65 73 28 44 29 5d 20  tal_changes(D)] 
1e1f0 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1e200 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d 62 65  eports the numbe
1e210 72 0a 2a 2a 20 6f 66 20 72 6f 77 73 20 74 68 61  r.** of rows tha
1e220 74 20 63 68 61 6e 67 65 64 20 64 75 65 20 74 6f  t changed due to
1e230 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 72   SQL statement r
1e240 75 6e 20 61 67 61 69 6e 73 74 20 64 61 74 61 62  un against datab
1e250 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
1e260 6e 20 44 2e 20 20 41 6e 79 20 63 68 61 6e 67 65  n D.  Any change
1e270 73 20 62 79 20 6f 74 68 65 72 20 64 61 74 61 62  s by other datab
1e280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1e290 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20  are ignored..** 
1e2a0 54 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65  To detect change
1e2b0 73 20 61 67 61 69 6e 73 74 20 61 20 64 61 74 61  s against a data
1e2c0 62 61 73 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f  base file from o
1e2d0 74 68 65 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ther database.**
1e2e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65   connections use
1e2f0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 64 61 74   the [PRAGMA dat
1e300 61 5f 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61  a_version] comma
1e310 6e 64 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51  nd or the.** [SQ
1e320 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f  LITE_FCNTL_DATA_
1e330 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63  VERSION] [file c
1e340 6f 6e 74 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20  ontrol]..** .** 
1e350 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1e360 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1e370 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1e380 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e390 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1e3a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1e3b0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1e3c0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
1e3d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
1e3e0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1e3f0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1e400 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1e410 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1e420 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
1e430 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1e440 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b  ce.** <li> the [
1e450 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1e460 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68  agma].** <li> th
1e470 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1e480 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c   function].** <l
1e490 69 3e 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72  i> the [data_ver
1e4a0 73 69 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20  sion pragma].** 
1e4b0 3c 6c 69 3e 20 74 68 65 20 5b 53 51 4c 49 54 45  <li> the [SQLITE
1e4c0 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53  _FCNTL_DATA_VERS
1e4d0 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ION] [file contr
1e4e0 6f 6c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ol].** </ul>.*/.
1e4f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
1e500 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
1e510 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1e520 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
1e530 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
1e540 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  uery.** METHOD: 
1e550 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1e560 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
1e570 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
1e580 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1e590 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
1e5a0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
1e5b0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
1e5c0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
1e5d0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
1e5e0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
1e5f0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
1e600 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
1e610 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
1e620 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
1e630 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
1e640 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
1e650 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
1e660 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
1e670 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
1e680 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1e690 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
1e6a0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
1e6b0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
1e6c0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
1e6d0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
1e6e0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
1e6f0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
1e700 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
1e710 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1e720 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
1e730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1e740 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
1e750 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
1e760 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
1e770 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
1e780 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
1e790 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1e7a0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
1e7b0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
1e7c0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
1e7d0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1e7e0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
1e7f0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
1e800 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
1e810 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
1e820 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
1e830 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
1e840 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
1e850 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1e860 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
1e870 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
1e880 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1e890 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
1e8a0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
1e8b0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
1e8c0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
1e8d0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
1e8e0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
1e8f0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1e900 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
1e910 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
1e920 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
1e930 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
1e940 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
1e950 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1e960 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
1e970 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
1e980 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
1e990 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1e9a0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
1e9b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1e9c0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
1e9d0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
1e9e0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1e9f0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1ea00 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1ea10 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
1ea20 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
1ea30 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
1ea40 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1ea50 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
1ea60 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
1ea70 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
1ea80 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
1ea90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1eaa0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
1eab0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1eac0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1ead0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
1eae0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
1eaf0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
1eb00 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
1eb10 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
1eb20 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
1eb30 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
1eb40 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
1eb50 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
1eb60 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
1eb70 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1eb80 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
1eb90 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
1eba0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
1ebb0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1ebc0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1ebd0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1ebe0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
1ebf0 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  urns..*/.void sq
1ec00 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1ec10 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1ec20 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1ec30 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1ec40 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
1ec50 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
1ec60 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
1ec70 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
1ec80 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
1ec90 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
1eca0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
1ecb0 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
1ecc0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
1ecd0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1ece0 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
1ecf0 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
1ed00 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
1ed10 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
1ed20 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
1ed30 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
1ed40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1ed50 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
1ed60 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
1ed70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
1ed80 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1ed90 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
1eda0 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
1edb0 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
1edc0 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
1edd0 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
1ede0 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
1edf0 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
1ee00 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
1ee10 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
1ee20 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
1ee30 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
1ee40 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
1ee50 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
1ee60 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
1ee70 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
1ee80 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
1ee90 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
1eea0 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
1eeb0 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
1eec0 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
1eed0 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
1eee0 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
1eef0 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
1ef00 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
1ef10 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
1ef20 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
1ef30 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
1ef40 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
1ef50 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
1ef60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1ef70 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
1ef80 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
1ef90 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
1efa0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1efb0 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
1efc0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
1efd0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
1efe0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
1eff0 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
1f000 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
1f010 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
1f020 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
1f030 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
1f040 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
1f050 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
1f060 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
1f070 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
1f080 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
1f090 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
1f0a0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
1f0b0 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
1f0c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1f0d0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1f0e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1f0f0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1f100 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
1f110 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
1f120 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
1f130 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1f140 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
1f150 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
1f160 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
1f170 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1f180 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
1f190 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
1f1a0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
1f1b0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1f1c0 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
1f1d0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1f1e0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
1f1f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
1f200 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1f210 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1f220 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1f230 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1f240 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1f250 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1f260 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
1f270 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1f280 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
1f290 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1f2a0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
1f2b0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
1f2c0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
1f2d0 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
1f2e0 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
1f2f0 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57  Y Errors.** KEYW
1f300 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64  ORDS: {busy-hand
1f310 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62  ler callback} {b
1f320 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20  usy handler}.** 
1f330 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1f340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f350 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1f360 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73  D,X,P) routine s
1f370 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
1f380 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61  unction X.** tha
1f390 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
1f3a0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
1f3b0 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61   P whenever.** a
1f3c0 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1f3d0 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61  e to access a da
1f3e0 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73  tabase table ass
1f3f0 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
1f400 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f410 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f  tion] D when ano
1f420 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
1f430 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68  r process has th
1f440 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a  e table locked..
1f450 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1f460 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e  usy_handler() in
1f470 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
1f480 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20  to implement.** 
1f490 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1f4a0 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52  meout()] and [PR
1f4b0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1f4c0 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  t]..**.** ^If th
1f4d0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1f4e0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
1f4f0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69  QLITE_BUSY].** i
1f500 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1f510 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
1f520 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
1f530 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
1f540 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1f550 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
1f560 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
1f570 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1f580 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
1f590 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1f5a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1f5b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1f5c0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1f5d0 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
1f5e0 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
1f5f0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
1f600 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1f610 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
1f620 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1f630 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1f640 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
1f650 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1f660 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
1f670 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
1f680 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70  * been invoked p
1f690 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68  reviously for th
1f6a0 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
1f6b0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1f6c0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1f6d0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1f6e0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1f6f0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1f700 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1f710 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1f720 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
1f730 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
1f740 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
1f750 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1f760 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1f770 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1f780 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1f790 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
1f7a0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1f7b0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
1f7c0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
1f7d0 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
1f7e0 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
1f7f0 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
1f800 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
1f810 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
1f820 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
1f830 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
1f840 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
1f850 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
1f860 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
1f870 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
1f880 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
1f890 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
1f8a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
1f8b0 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
1f8c0 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
1f8d0 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1f8e0 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
1f8f0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
1f900 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
1f910 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
1f920 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
1f930 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
1f940 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
1f950 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
1f960 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
1f970 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
1f980 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
1f990 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
1f9a0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
1f9b0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
1f9c0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
1f9d0 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
1f9e0 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
1f9f0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
1fa00 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1fa10 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
1fa20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
1fa30 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
1fa40 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1fa50 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
1fa60 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
1fa70 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
1fa80 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
1fa90 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
1faa0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
1fab0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
1fac0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
1fad0 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
1fae0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
1faf0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
1fb00 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
1fb10 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
1fb20 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
1fb30 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
1fb40 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
1fb50 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1fb60 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
1fb70 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1fb80 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
1fb90 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
1fba0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1fbb0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1fbc0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
1fbd0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
1fbe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fbf0 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
1fc00 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
1fc10 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
1fc20 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
1fc30 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
1fc40 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
1fc50 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1fc60 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
1fc70 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
1fc80 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
1fc90 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
1fca0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
1fcb0 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
1fcc0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1fcd0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1fce0 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
1fcf0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
1fd00 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
1fd10 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
1fd20 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
1fd30 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1fd40 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1fd50 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
1fd60 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
1fd70 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1fd80 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
1fd90 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
1fda0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
1fdb0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
1fdc0 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
1fdd0 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1fde0 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
1fdf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1fe00 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
1fe10 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1fe20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1fe30 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
1fe40 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1fe50 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69  ndler(sqlite3*,i
1fe60 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1fe70 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ,void*);../*.** 
1fe80 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
1fe90 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20  Busy Timeout.** 
1fea0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1feb0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1fec0 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
1fed0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1fee0 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
1fef0 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
1ff00 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
1ff10 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
1ff20 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
1ff30 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
1ff40 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
1ff50 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
1ff60 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
1ff70 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1ff80 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
1ff90 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
1ffa0 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
1ffb0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1ffc0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1ffd0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
1ffe0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
1fff0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
20000 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
20010 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
20020 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  BUSY]..**.** ^Ca
20030 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
20040 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
20050 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
20060 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
20070 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
20080 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
20090 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
200a0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
200b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
200c0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
200d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
200e0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20  nection] at any 
200f0 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
20100 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
20110 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
20120 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
20130 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
20140 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
20150 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
20160 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
20170 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
20180 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
20190 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
201a0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
201b0 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71  meout].*/.int sq
201c0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
201d0 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
201e0 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
201f0 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
20200 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
20210 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
20220 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
20230 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e3.**.** This is
20240 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
20250 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
20260 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
20270 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
20280 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
20290 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
202a0 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
202b0 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
202c0 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
202d0 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
202e0 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
202f0 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
20300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
20310 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
20320 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
20330 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
20340 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
20350 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
20360 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
20370 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
20380 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
20390 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
203a0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
203b0 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
203c0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
203d0 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
203e0 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
203f0 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
20400 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
20410 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
20420 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
20430 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
20440 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
20450 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
20460 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
20470 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
20480 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
20490 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
204a0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
204b0 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
204c0 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
204d0 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
204e0 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
204f0 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
20500 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
20510 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
20520 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
20530 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
20540 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
20550 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
20560 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
20570 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
20580 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
20590 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
205a0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
205b0 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
205c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
205d0 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
205e0 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
205f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
20600 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
20610 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
20620 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
20630 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
20640 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
20650 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
20660 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
20670 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
20680 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
20690 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
206a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
206b0 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
206c0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
206d0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
206e0 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
206f0 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
20700 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
20710 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
20720 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
20730 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
20740 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
20750 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
20760 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
20770 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
20780 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
20790 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
207a0 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
207b0 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
207c0 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
207d0 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
207e0 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
207f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
20800 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
20810 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
20820 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
20830 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
20840 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
20850 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
20860 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
20870 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
20880 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
20890 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
208a0 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
208b0 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
208c0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
208d0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
208e0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
208f0 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
20900 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
20910 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
20920 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
20930 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
20940 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
20950 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
20960 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
20970 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
20980 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
20990 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
209a0 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
209b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
209c0 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
209d0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
209e0 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
209f0 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
20a00 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
20a10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20a20 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
20a30 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
20a40 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
20a50 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
20a60 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
20a70 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
20a80 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
20a90 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
20aa0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
20ab0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
20ac0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
20ad0 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
20ae0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
20af0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
20b00 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
20b10 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
20b20 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
20b30 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
20b40 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
20b50 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
20b60 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
20b70 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
20b80 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
20b90 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
20ba0 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
20bb0 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
20bc0 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
20bd0 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
20be0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
20bf0 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
20c00 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
20c10 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
20c20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
20c30 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
20c40 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
20c50 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
20c60 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
20c70 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
20c80 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
20c90 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
20ca0 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
20cb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
20cc0 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
20cd0 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
20ce0 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
20cf0 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
20d00 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
20d10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
20d20 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
20d30 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
20d40 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
20d50 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
20d60 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
20d70 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
20d80 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
20d90 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
20da0 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
20db0 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
20dc0 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
20dd0 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
20de0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
20df0 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
20e00 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
20e10 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
20e20 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
20e30 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
20e40 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
20e50 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
20e60 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
20e70 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
20e80 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
20e90 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
20ea0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
20eb0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
20ec0 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
20ed0 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
20ee0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
20ef0 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
20f00 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
20f10 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
20f20 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
20f30 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
20f40 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
20f50 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
20f60 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
20f70 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
20f80 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
20f90 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
20fa0 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
20fb0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
20fc0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
20fd0 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
20fe0 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
20ff0 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
21000 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
21010 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
21020 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
21030 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
21040 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
21050 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
21060 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
21070 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
21080 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
21090 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
210a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e  hese routines un
210b0 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66  derstand most of
210c0 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d   the common form
210d0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66  atting options f
210e0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
210f0 61 72 64 20 6c 69 62 72 61 72 79 20 70 72 69 6e  ard library prin
21100 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f  tf() .** plus so
21110 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f  me additional no
21120 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61  n-standard forma
21130 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20  ts ([%q], [%Q], 
21140 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e  [%w], and [%z]).
21150 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 62 75 69  .** See the [bui
21160 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 20  lt-in printf()] 
21170 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
21180 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  r details..**.**
21190 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
211a0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
211b0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
211c0 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
211d0 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
211e0 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
211f0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
21200 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a  3_malloc64()]..*
21210 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
21220 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
21230 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
21240 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
21250 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
21260 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
21270 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
21280 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
21290 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
212a0 6c 6f 63 36 34 28 29 5d 20 69 73 20 75 6e 61 62  loc64()] is unab
212b0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
212c0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
212d0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
212e0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
212f0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
21300 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
21310 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
21320 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
21330 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
21340 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
21350 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
21360 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
21370 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
21380 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
21390 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
213a0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
213b0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
213c0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
213d0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
213e0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
213f0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
21400 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
21410 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
21420 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
21430 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
21440 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
21450 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
21460 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
21470 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
21480 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
21490 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
214a0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
214b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
214c0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
214d0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
214e0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
214f0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
21500 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
21510 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
21520 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
21530 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
21540 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
21550 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
21560 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
21570 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
21580 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
21590 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
215a0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
215b0 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
215c0 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
215d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
215e0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
215f0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
21600 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
21610 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
21620 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
21630 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
21640 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
21650 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
21660 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
21670 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
21680 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
21690 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
216a0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
216b0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
216c0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
216d0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
216e0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
216f0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
21700 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
21710 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
21720 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
21730 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
21740 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
21750 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
21760 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  f()..**.** See a
21770 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20  lso:  [built-in 
21780 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e  printf()], [prin
21790 74 66 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  tf() SQL functio
217a0 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  n].*/.char *sqli
217b0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
217c0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
217d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
217e0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
217f0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
21800 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
21810 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
21820 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
21830 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
21840 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
21850 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
21860 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
21870 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
21880 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
21890 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
218a0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
218b0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
218c0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
218d0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
218e0 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
218f0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
21900 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
21910 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
21920 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
21930 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
21940 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
21950 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
21960 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
21970 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
21980 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
21990 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
219a0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
219b0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
219c0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
219d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
219e0 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
219f0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
21a00 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
21a10 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
21a20 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
21a30 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
21a40 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
21a50 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
21a60 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
21a70 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
21a80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
21a90 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
21aa0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
21ab0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
21ac0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
21ad0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
21ae0 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
21af0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
21b00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
21b10 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
21b20 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
21b30 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
21b40 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
21b50 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
21b60 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
21b70 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
21b80 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
21b90 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
21ba0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
21bb0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
21bc0 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
21bd0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
21be0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
21bf0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
21c00 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
21c10 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
21c20 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
21c30 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
21c40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
21c50 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
21c60 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
21c70 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
21c80 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
21c90 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
21ca0 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
21cb0 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
21cc0 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
21cd0 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
21ce0 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
21cf0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
21d00 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
21d10 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
21d20 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
21d30 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
21d40 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
21d50 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
21d60 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
21d70 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
21d80 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
21d90 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
21da0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
21db0 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
21dc0 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
21dd0 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
21de0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
21df0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
21e00 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
21e10 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
21e20 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
21e30 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
21e40 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
21e50 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
21e60 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
21e70 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
21e80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
21e90 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
21ea0 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
21eb0 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
21ec0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
21ed0 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
21ee0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
21ef0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
21f00 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
21f10 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
21f20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
21f30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
21f40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
21f50 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
21f60 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
21f70 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
21f80 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
21f90 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
21fa0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
21fb0 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
21fc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
21fd0 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
21fe0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
21ff0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
22000 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
22010 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
22020 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
22030 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
22040 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
22050 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
22060 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
22070 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
22080 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
22090 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
220a0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
220b0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
220c0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
220d0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
220e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
220f0 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
22100 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
22110 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
22120 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
22130 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
22140 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
22150 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
22160 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
22170 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
22180 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22190 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
221a0 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
221b0 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
221c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
221d0 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
221e0 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
221f0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
22200 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
22210 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
22220 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
22230 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
22240 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
22250 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
22260 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
22270 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
22280 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
22290 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
222a0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
222b0 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
222c0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
222d0 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
222e0 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
222f0 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
22300 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
22310 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
22320 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
22330 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
22340 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
22350 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
22360 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
22370 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
22380 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
22390 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
223a0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
223b0 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
223c0 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
223d0 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
223e0 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
223f0 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
22400 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
22410 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
22420 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
22430 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
22440 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
22450 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
22460 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
22470 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
22480 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
22490 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
224a0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
224b0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
224c0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
224d0 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
224e0 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
224f0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
22500 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
22510 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
22520 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
22530 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
22540 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
22550 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
22560 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
22570 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
22580 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
22590 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
225a0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
225b0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
225c0 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
225d0 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
225e0 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
225f0 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
22600 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
22610 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
22620 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
22630 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
22640 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
22650 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
22660 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
22670 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
22680 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
22690 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
226a0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
226b0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
226c0 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
226d0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
226e0 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
226f0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
22700 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
22710 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
22720 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
22730 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
22740 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
22750 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
22760 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
22770 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
22780 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
22790 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
227a0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
227b0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
227c0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
227d0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
227e0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
227f0 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
22800 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
22810 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
22820 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
22830 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
22840 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
22850 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
22860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
22870 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
22880 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
22890 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
228a0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
228b0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
228c0 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
228d0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
228e0 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
228f0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
22900 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
22910 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
22920 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
22930 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
22940 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
22950 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
22960 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
22970 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
22980 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
22990 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
229a0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
229b0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
229c0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
229d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
229e0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
229f0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
22a00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
22a10 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
22a20 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
22a30 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
22a40 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
22a50 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
22a60 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
22a70 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
22a80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
22a90 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
22aa0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
22ab0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
22ac0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
22ad0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
22ae0 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
22af0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
22b00 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
22b10 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
22b20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
22b30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
22b40 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
22b50 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
22b60 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
22b70 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
22b80 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
22b90 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
22ba0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
22bb0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
22bc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
22bd0 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
22be0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
22bf0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
22c00 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
22c10 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
22c20 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
22c30 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
22c40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
22c50 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
22c60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
22c70 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
22c80 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
22c90 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
22ca0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
22cb0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
22cc0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
22cd0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
22ce0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
22cf0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
22d00 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
22d10 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
22d20 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
22d30 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
22d40 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
22d50 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
22d60 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
22d70 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
22d80 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
22d90 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
22da0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
22db0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
22dc0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
22dd0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
22de0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
22df0 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
22e00 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
22e10 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
22e20 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
22e30 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
22e40 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
22e50 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
22e60 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
22e70 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
22e80 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
22e90 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
22ea0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
22eb0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
22ec0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
22ed0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
22ee0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
22ef0 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
22f00 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
22f10 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
22f20 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
22f30 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
22f40 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
22f50 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
22f60 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
22f70 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
22f80 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
22f90 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
22fa0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
22fb0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
22fc0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
22fd0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
22fe0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
22ff0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
23000 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
23010 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
23020 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
23030 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
23040 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
23050 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
23060 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
23070 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
23080 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
23090 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
230a0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
230b0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
230c0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
230d0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
230e0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
230f0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
23100 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
23110 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
23120 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
23130 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
23140 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
23150 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
23160 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
23170 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
23180 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
23190 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
231a0 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
231b0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
231c0 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
231d0 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
231e0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
231f0 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
23200 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
23210 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
23220 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
23230 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
23240 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
23250 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
23260 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
23270 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
23280 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
23290 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
232a0 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
232b0 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
232c0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
232d0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
232e0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
232f0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
23300 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
23310 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
23320 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
23330 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
23340 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
23350 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
23360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23370 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
23380 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
23390 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
233a0 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f  sqlite3.** KEYWO
233b0 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72  RDS: {authorizer
233c0 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a   callback}.**.**
233d0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
233e0 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
233f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
23400 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
23410 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
23420 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
23430 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
23440 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
23450 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
23460 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
23470 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
23480 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
23490 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
234a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
234b0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
234c0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
234d0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
234e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
234f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
23500 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c  epare16()], [sql
23510 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
23520 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71  2()],.** and [sq
23530 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
23540 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v3()].  ^At vari
23550 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
23560 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
23570 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
23580 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
23590 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
235a0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
235b0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
235c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
235d0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
235e0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
235f0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
23600 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
23610 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
23620 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
23630 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
23640 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
23650 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
23660 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
23670 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
23680 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
23690 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
236a0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
236b0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
236c0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
236d0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
236e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
236f0 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
23700 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
23710 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
23720 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
23730 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
23740 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
23750 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
23760 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
23770 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
23780 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
23790 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
237a0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
237b0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
237c0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
237d0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
237e0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
237f0 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
23800 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
23810 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
23820 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
23830 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
23840 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
23850 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
23860 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
23870 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
23880 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23890 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
238a0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
238b0 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
238c0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
238d0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
238e0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
238f0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
23900 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
23910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
23920 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
23930 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
23940 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
23950 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
23960 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
23970 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
23980 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
23990 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
239a0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
239b0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
239c0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
239d0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
239e0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
239f0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
23a00 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
23a10 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
23a20 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
23a30 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
23a40 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
23a50 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69   callback are ei
23a60 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ther NULL pointe
23a70 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69  rs or zero-termi
23a80 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  nated strings.**
23a90 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
23aa0 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
23ab0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
23ac0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
23ad0 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  ed..** Applicati
23ae0 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ons must always 
23af0 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 65  be prepared to e
23b00 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20  ncounter a NULL 
23b10 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a  pointer in any.*
23b20 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74  * of the third t
23b30 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 68  hrough the sixth
23b40 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
23b50 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
23b60 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
23b70 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
23b80 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
23b90 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
23ba0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
23bb0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
23bc0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
23bd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23be0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
23bf0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
23c00 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
23c10 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
23c20 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
23c30 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
23c40 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
23c50 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
23c60 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
23c70 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
23c80 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
23c90 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
23ca0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
23cb0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
23cc0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
23cd0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
23ce0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20  table..** ^When 
23cf0 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72  a table is refer
23d00 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45  enced by a [SELE
23d10 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d  CT] but no colum
23d20 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20  n values are.** 
23d30 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74  extracted from t
23d40 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65  hat table (for e
23d50 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72  xample in a quer
23d60 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43  y like.** "SELEC
23d70 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20  T count(*) FROM 
23d80 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b  tab") then the [
23d90 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74  SQLITE_READ] aut
23da0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
23db0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  .** is invoked o
23dc0 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 62  nce for that tab
23dd0 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e  le with a column
23de0 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e   name that is an
23df0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
23e00 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
23e10 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
23e20 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
23e30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
23e40 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
23e50 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
23e60 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
23e70 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
23e80 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
23e90 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
23ea0 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
23eb0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
23ec0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
23ed0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
23ee0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
23ef0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23f00 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
23f10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
23f20 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
23f30 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
23f40 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
23f50 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
23f60 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
23f70 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
23f80 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
23f90 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
23fa0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
23fb0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
23fc0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
23fd0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
23fe0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
23ff0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
24000 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
24010 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
24020 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
24030 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
24040 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
24050 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
24060 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
24070 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
24080 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
24090 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
240a0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
240b0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
240c0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
240d0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
240e0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
240f0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
24100 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
24110 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
24120 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
24130 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
24140 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
24150 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
24160 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
24170 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
24180 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
24190 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
241a0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
241b0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
241c0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
241d0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
241e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
241f0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
24200 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
24210 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
24220 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
24230 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
24240 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
24250 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
24260 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
24270 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
24280 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
24290 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
242a0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
242b0 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
242c0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
242d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
242e0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
242f0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
24300 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
24310 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
24320 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
24330 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
24340 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
24350 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
24360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
24370 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
24380 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
24390 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
243a0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
243b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
243c0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
243d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
243e0 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
243f0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
24400 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
24410 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
24420 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
24430 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
24440 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
24450 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
24460 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
24470 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
24480 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
24490 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
244a0 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
244b0 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
244c0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
244d0 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
244e0 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
244f0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
24500 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
24510 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
24520 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
24530 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
24540 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
24550 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
24560 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
24570 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
24580 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
24590 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
245a0 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
245b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
245c0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
245d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
245e0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
245f0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
24600 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
24610 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
24620 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
24630 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
24640 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
24650 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
24660 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
24670 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
24680 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
24690 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
246a0 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
246b0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
246c0 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
246d0 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
246e0 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
246f0 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
24700 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
24710 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
24720 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
24730 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
24740 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
24750 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
24760 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
24770 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
24780 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
24790 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
247a0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
247b0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
247c0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
247d0 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
247e0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
247f0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
24800 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
24810 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
24820 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
24830 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
24840 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
24850 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
24860 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
24870 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
24880 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
24890 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
248a0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
248b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
248c0 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
248d0 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
248e0 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
248f0 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
24900 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
24910 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
24920 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
24930 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
24940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
24950 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
24960 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
24970 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
24980 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
24990 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
249a0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
249b0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
249c0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
249d0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
249e0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
249f0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
24a00 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
24a10 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
24a20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
24a30 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
24a40 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
24a50 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
24a60 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
24a70 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
24a80 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
24a90 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
24aa0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
24ab0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
24ac0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
24ad0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
24ae0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
24af0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
24b00 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
24b10 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
24b20 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
24b30 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
24b40 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
24b50 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
24b60 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
24b70 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
24b80 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
24b90 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
24ba0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
24bb0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
24bc0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
24bd0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
24be0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
24bf0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
24c00 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
24c10 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
24c20 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
24c30 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
24c40 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
24c50 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
24c60 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
24c70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
24c80 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
24c90 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
24ca0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
24cb0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
24cc0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
24cd0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
24ce0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
24cf0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
24d00 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
24d10 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
24d20 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
24d30 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
24d40 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
24d50 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
24d60 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
24d70 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
24d80 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
24d90 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
24da0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24db0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24dc0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
24dd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
24de0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
24df0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
24e00 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
24e10 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
24e20 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
24e30 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
24e40 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
24e50 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
24e60 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24e70 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
24e80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24e90 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
24ea0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
24eb0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
24ec0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
24ed0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24ee0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
24ef0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
24f00 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24f10 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24f20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24f30 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
24f40 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
24f50 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
24f60 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24f70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24f80 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
24f90 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
24fa0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
24fb0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24fc0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24fd0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
24fe0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
24ff0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
25000 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
25010 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
25020 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
25030 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
25040 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
25050 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
25060 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25070 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
25080 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
25090 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
250a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
250b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
250c0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
250d0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
250e0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
250f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
25100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25110 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
25120 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
25130 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
25140 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
25150 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
25160 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
25170 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
25180 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
25190 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
251a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
251b0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
251c0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
251d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
251e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
251f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
25200 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
25210 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
25220 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
25230 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
25240 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
25250 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
25260 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
25270 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
25280 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
25290 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
252a0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
252b0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
252c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
252d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
252e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
252f0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
25300 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
25310 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
25320 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
25330 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
25340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
25350 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
25360 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
25370 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
25380 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
25390 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
253a0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
253b0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
253c0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
253d0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
253e0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
253f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
25400 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
25410 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
25420 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
25430 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
25440 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
25450 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
25460 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
25470 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
25480 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
25490 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
254a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
254b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
254c0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
254d0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
254e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
254f0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
25500 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
25510 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
25520 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
25530 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
25540 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
25550 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25560 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
25570 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
25580 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
25590 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
255a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
255b0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
255c0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
255d0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
255e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
255f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25600 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
25610 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
25620 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
25630 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
25640 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
25650 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
25660 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
25670 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
25680 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
25690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
256a0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
256b0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
256c0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
256d0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
256e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
256f0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
25700 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
25710 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
25720 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
25730 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
25740 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
25750 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
25760 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
25770 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
25780 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
25790 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
257a0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
257b0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
257c0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
257d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
257e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
257f0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
25800 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
25810 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
25820 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
25830 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
25840 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
25850 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
25860 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
25870 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
25880 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
25890 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
258a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
258b0 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
258c0 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
258d0 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e  3_trace_v2()] in
258e0 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65  terface.** inste
258f0 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e  ad of the routin
25900 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72  es described her
25910 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
25920 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
25930 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
25940 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
25950 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
25960 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
25970 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
25980 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
25990 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
259a0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
259b0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
259c0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
259d0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
259e0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
259f0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
25a00 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
25a10 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
25a20 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
25a30 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
25a40 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
25a50 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
25a60 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
25a70 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
25a80 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
25a90 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
25aa0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
25ab0 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
25ac0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
25ad0 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
25ae0 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
25af0 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
25b00 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
25b10 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
25b20 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
25b30 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
25b40 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
25b50 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
25b60 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
25b70 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
25b80 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
25b90 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
25ba0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
25bb0 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
25bc0 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
25bd0 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
25be0 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
25bf0 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
25c00 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
25c10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
25c20 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
25c30 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
25c40 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
25c50 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
25c60 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
25c70 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
25c80 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
25c90 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
25ca0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
25cb0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
25cc0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
25cd0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
25ce0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
25cf0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
25d00 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
25d10 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
25d20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
25d30 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
25d40 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
25d50 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
25d60 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
25d70 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
25d80 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
25d90 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
25da0 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
25db0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
25dc0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
25dd0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
25de0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
25df0 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
25e00 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
25e10 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
25e20 62 61 63 6b 2e 20 20 49 6e 76 6f 6b 69 6e 67 0a  back.  Invoking.
25e30 2a 2a 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ** either [sqlit
25e40 65 33 5f 74 72 61 63 65 28 29 5d 20 6f 72 20 5b  e3_trace()] or [
25e50 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
25e60 28 29 5d 20 77 69 6c 6c 20 63 61 6e 63 65 6c 20  ()] will cancel 
25e70 74 68 65 0a 2a 2a 20 70 72 6f 66 69 6c 65 20 63  the.** profile c
25e80 61 6c 6c 62 61 63 6b 2e 0a 2a 2f 0a 53 51 4c 49  allback..*/.SQLI
25e90 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
25ea0 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
25eb0 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
25ec0 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
25ed0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
25ee0 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
25ef0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
25f00 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
25f10 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
25f20 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
25f30 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
25f40 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
25f50 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
25f60 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72  CAPI3REF: SQL Tr
25f70 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a  ace Event Codes.
25f80 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
25f90 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20  ITE_TRACE.**.** 
25fa0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
25fb0 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73  identify classes
25fc0 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74 20   of events that 
25fd0 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64  can be monitored
25fe0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73  .** using the [s
25ff0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
26000 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63  )] tracing logic
26010 2e 20 20 54 68 65 20 4d 20 61 72 67 75 6d 65 6e  .  The M argumen
26020 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
26030 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c  _trace_v2(D,M,X,
26040 50 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20  P)] is an OR-ed 
26050 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f  combination of o
26060 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a  ne or more of.**
26070 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
26080 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20  onstants.  ^The 
26090 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
260a0 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
260b0 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f  back.** is one o
260c0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
260d0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
260e0 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e   New tracing con
260f0 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64  stants may be ad
26100 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
26110 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  leases..**.** ^A
26120 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
26130 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  has four argumen
26140 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c  ts: xCallback(T,
26150 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20  C,P,X)..** ^The 
26160 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  T argument is on
26170 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  e of the integer
26180 20 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76   type codes abov
26190 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  e..** ^The C arg
261a0 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
261b0 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
261c0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
261d0 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
261e0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
261f0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
26200 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64  )]..** The P and
26210 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65   X arguments are
26220 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20   pointers whose 
26230 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20  meanings depend 
26240 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  on T..**.** <dl>
26250 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
26260 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51  CE_STMT]] <dt>SQ
26270 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c  LITE_TRACE_STMT<
26280 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
26290 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
262a0 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  T callback is in
262b0 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65  voked when a pre
262c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
262d0 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  ** first begins 
262e0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73  running and poss
262f0 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69  ibly at other ti
26300 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a  mes during the.*
26310 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  * execution of t
26320 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
26330 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61  ement, such as a
26340 74 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65  t the start of e
26350 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73  ach.** trigger s
26360 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20  ubprogram. ^The 
26370 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
26380 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
26390 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
263a0 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61  ement]. ^The X a
263b0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
263c0 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
263d0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
263e0 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20   unexpanded SQL 
263f0 74 65 78 74 20 6f 66 20 74 68 65 20 70 72 65 70  text of the prep
26400 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
26410 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  r an SQL comment
26420 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
26430 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69  tes the invocati
26440 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e  on of a trigger.
26450 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20    ^The callback 
26460 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74  can compute.** t
26470 68 65 20 73 61 6d 65 20 74 65 78 74 20 74 68 61  he same text tha
26480 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65  t would have bee
26490 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
264a0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
264b0 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e  3_trace()].** in
264c0 74 65 72 66 61 63 65 20 62 79 20 75 73 69 6e 67  terface by using
264d0 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
264e0 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69  when X begins wi
264f0 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f  th "--" and invo
26500 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  king.** [sqlite3
26510 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
26520 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  ] otherwise..**.
26530 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
26540 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e  E_PROFILE]] <dt>
26550 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
26560 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FILE</dt>.** <dd
26570 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
26580 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61  E_PROFILE callba
26590 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70 72  ck provides appr
265a0 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61  oximately the sa
265b0 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  me.** informatio
265c0 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64 65 64  n as is provided
265d0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
265e0 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c  _profile()] call
265f0 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  back..** ^The P 
26600 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
26610 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72  inter to the [pr
26620 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26630 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61  ] and the.** X a
26640 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
26650 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67  o a 64-bit integ
26660 65 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20  er which is the 
26670 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20  estimated of.** 
26680 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61  the number of na
26690 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68  nosecond that th
266a0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
266b0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
266c0 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
266d0 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
266e0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
266f0 65 64 20 77 68 65 6e 20 74 68 65 20 73 74 61 74  ed when the stat
26700 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a  ement finishes..
26710 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
26720 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53  RACE_ROW]] <dt>S
26730 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c  QLITE_TRACE_ROW<
26740 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
26750 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
26760 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
26770 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
26780 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
26790 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20  ement generates 
267a0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
267b0 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68  result.  .** ^Th
267c0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
267d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
267e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
267f0 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
26800 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75   X argument is u
26810 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  nused..**.** [[S
26820 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
26830 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
26840 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a  RACE_CLOSE</dt>.
26850 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
26860 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61  E_TRACE_CLOSE ca
26870 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
26880 64 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  d when a databas
26890 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
268a0 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20  closes..** ^The 
268b0 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
268c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
268d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
268e0 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  ion] object.** a
268f0 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  nd the X argumen
26900 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20  t is unused..** 
26910 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
26920 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54   SQLITE_TRACE_ST
26930 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a 23 64  MT       0x01.#d
26940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
26950 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78  CE_PROFILE    0x
26960 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
26970 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20  E_TRACE_ROW     
26980 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20     0x04.#define 
26990 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
269a0 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a  SE      0x08../*
269b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
269c0 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20  L Trace Hook.** 
269d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
269e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
269f0 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c  e3_trace_v2(D,M,
26a00 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  X,P) interface r
26a10 65 67 69 73 74 65 72 73 20 61 20 74 72 61 63 65  egisters a trace
26a20 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
26a30 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20  ction X against 
26a40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
26a50 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70  tion] D, using p
26a60 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a  roperty mask M.*
26a70 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f  * and context po
26a80 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68  inter P.  ^If th
26a90 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a  e X callback is.
26aa0 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68  ** NULL or if th
26ab0 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f  e M mask is zero
26ac0 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69  , then tracing i
26ad0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65  s disabled.  The
26ae0 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73  .** M argument s
26af0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69 74  hould be the bit
26b00 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69  wise OR-ed combi
26b10 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72  nation of.** zer
26b20 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54  o or more [SQLIT
26b30 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e  E_TRACE] constan
26b40 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  ts..**.** ^Each 
26b50 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73  call to either s
26b60 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
26b70 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
26b80 76 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a  v2() overrides .
26b90 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79  ** (cancels) any
26ba0 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20   prior calls to 
26bb0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
26bc0 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
26bd0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  _v2()..**.** ^Th
26be0 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e X callback is 
26bf0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
26c00 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e   any of the even
26c10 74 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ts identified by
26c20 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75   .** mask M occu
26c30 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72  r.  ^The integer
26c40 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
26c50 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  om the callback 
26c60 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  is currently.** 
26c70 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20  ignored, though 
26c80 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20  this may change 
26c90 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
26ca0 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a  es.  Callback.**
26cb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
26cc0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a   should return z
26cd0 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75  ero to ensure fu
26ce0 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69  ture compatibili
26cf0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61  ty..**.** ^A tra
26d00 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ce callback is i
26d10 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72  nvoked with four
26d20 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c   arguments: call
26d30 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
26d40 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
26d50 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
26d60 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a  [SQLITE_TRACE].*
26d70 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69  * constants to i
26d80 6e 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20  ndicate why the 
26d90 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76  callback was inv
26da0 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  oked..** ^The C 
26db0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
26dc0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
26dd0 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68  t pointer..** Th
26de0 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
26df0 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
26e00 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
26e10 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
26e20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74  ** The sqlite3_t
26e30 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66  race_v2() interf
26e40 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
26e50 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c  to replace the l
26e60 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
26e70 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  ces [sqlite3_tra
26e80 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ce()] and [sqlit
26e90 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62  e3_profile()], b
26ea0 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20  oth of which.** 
26eb0 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a  are deprecated..
26ec0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
26ed0 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  race_v2(.  sqlit
26ee0 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20  e3*,.  unsigned 
26ef0 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43  uMask,.  int(*xC
26f00 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65  allback)(unsigne
26f10 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f  d,void*,void*,vo
26f20 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43  id*),.  void *pC
26f30 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tx.);../*.** CAP
26f40 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
26f50 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
26f60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
26f70 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
26f80 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
26f90 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
26fa0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
26fb0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
26fc0 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
26fd0 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
26fe0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
26ff0 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
27000 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
27010 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
27020 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
27030 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
27040 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
27050 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
27060 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
27070 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
27080 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
27090 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
270a0 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
270b0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
270c0 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
270d0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
270e0 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
270f0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
27100 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
27110 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
27120 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61  meter N is the a
27130 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65  pproximate numbe
27140 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
27150 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
27160 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
27170 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
27180 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
27190 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
271a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20  the callback X. 
271b0 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74   ^If N is less t
271c0 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65  han one then the
271d0 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e   progress.** han
271e0 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  dler is disabled
271f0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
27200 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
27210 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
27220 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
27230 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
27240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
27250 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
27260 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
27270 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
27280 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
27290 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
272a0 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
272b0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
272c0 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
272d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
272e0 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
272f0 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
27300 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
27310 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
27320 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
27330 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
27340 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
27350 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
27360 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
27370 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
27380 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
27390 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
273a0 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
273b0 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
273c0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
273d0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
273e0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
273f0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
27400 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
27410 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
27420 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
27430 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
27440 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
27450 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
27460 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
27470 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
27480 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
27490 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
274a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
274b0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
274c0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
274d0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
274e0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
274f0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
27500 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
27510 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
27520 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
27530 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
27540 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
27550 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f  Connection.** CO
27560 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
27570 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
27580 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
27590 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
275a0 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
275b0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
275c0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
275d0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
275e0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
275f0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
27600 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
27610 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
27620 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
27630 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
27640 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
27650 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
27660 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
27670 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27680 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
27690 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
276a0 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
276b0 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
276c0 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
276d0 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
276e0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
276f0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
27700 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
27710 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
27720 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
27730 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
27740 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
27750 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
27760 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
27770 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
27780 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
27790 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
277a0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
277b0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
277c0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
277d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
277e0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
277f0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
27800 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
27810 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
27820 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
27830 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
27840 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
27850 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
27860 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
27870 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
27880 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
27890 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
278a0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
278b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
278c0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
278d0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
278e0 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46  ding will be UTF
278f0 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  -8 for databases
27900 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
27910 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
27920 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
27930 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66  _v2().  ^The def
27940 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
27950 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63  r databases.** c
27960 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c  reated using sql
27970 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69  ite3_open16() wi
27980 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20  ll be UTF-16 in 
27990 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
279a0 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  order..**.** Whe
279b0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
279c0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
279d0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
279e0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
279f0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
27a00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27a10 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
27a20 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
27a30 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
27a40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
27a50 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
27a60 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
27a70 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
27a80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27a90 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
27aa0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
27ab0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
27ac0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
27ad0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
27ae0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
27af0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
27b00 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
27b10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27b20 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
27b30 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
27b40 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
27b50 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
27b60 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
27b70 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
27b80 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
27b90 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
27ba0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
27bb0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
27bc0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
27bd0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
27be0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
27bf0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
27c00 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
27c10 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
27c20 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
27c30 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
27c40 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
27c50 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
27c60 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
27c70 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
27c80 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
27c90 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
27ca0 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
27cb0 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
27cc0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
27cd0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
27ce0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
27cf0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
27d00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
27d10 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
27d20 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
27d30 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
27d40 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
27d50 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
27d60 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
27d70 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
27d80 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
27d90 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
27da0 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
27db0 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
27dc0 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
27dd0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
27de0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
27df0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
27e00 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
27e10 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
27e20 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
27e30 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
27e40 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
27e50 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
27e60 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
27e70 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
27e80 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
27e90 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
27ea0 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
27eb0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
27ec0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
27ed0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
27ee0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
27ef0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
27f00 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
27f10 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
27f20 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
27f30 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
27f40 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
27f50 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
27f60 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
27f70 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
27f80 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
27f90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
27fa0 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
27fb0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
27fc0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
27fd0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
27fe0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
27ff0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
28000 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
28010 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
28020 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
28030 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
28040 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
28050 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
28060 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
28070 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
28080 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
28090 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
280a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
280b0 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
280c0 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
280d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
280e0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
280f0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
28100 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
28110 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
28120 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
28130 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
28140 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
28150 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
28160 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
28170 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
28180 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
28190 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
281a0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
281b0 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
281c0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
281d0 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
281e0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
281f0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
28200 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
28210 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
28220 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
28230 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
28240 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
28250 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
28260 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
28270 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
28280 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
28290 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
282a0 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
282b0 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
282c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
282d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
282e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
282f0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
28300 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
28310 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
28320 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
28330 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
28340 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
28350 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
28360 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
28370 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
28380 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
28390 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
283a0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
283b0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
283c0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
283d0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
283e0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
283f0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
28400 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
28410 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
28420 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
28430 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
28440 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
28450 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
28460 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
28470 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
28480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
28490 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
284a0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
284b0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
284c0 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
284d0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
284e0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
284f0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
28500 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
28510 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
28520 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
28530 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
28540 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
28550 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
28560 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
28570 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
28580 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
28590 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
285a0 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
285b0 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
285c0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
285d0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
285e0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
285f0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
28600 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
28610 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
28620 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
28630 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
28640 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
28650 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
28660 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
28670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28680 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
28690 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
286a0 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
286b0 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
286c0 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
286d0 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
286e0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
286f0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
28700 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
28710 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
28720 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
28730 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
28740 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
28750 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
28760 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
28770 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
28780 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
28790 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
287a0 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
287b0 65 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  et in the third 
287c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
287d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
287e0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
287f0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
28800 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
28810 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
28820 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
28830 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
28840 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
28850 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
28860 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
28870 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
28880 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
28890 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
288a0 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
288b0 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
288c0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
288d0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
288e0 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
288f0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
28900 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
28910 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
28920 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
28930 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
28940 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
28950 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
28960 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
28970 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
28980 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
28990 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
289a0 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
289b0 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
289c0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
289d0 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
289e0 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
289f0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
28a00 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
28a10 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
28a20 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
28a30 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
28a40 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
28a50 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
28a60 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
28a70 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
28a80 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
28a90 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
28aa0 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
28ab0 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
28ac0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
28ad0 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
28ae0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
28af0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
28b00 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
28b10 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
28b20 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
28b30 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
28b40 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
28b50 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
28b60 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
28b70 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
28b80 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
28b90 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
28ba0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
28bb0 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
28bc0 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
28bd0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
28be0 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
28bf0 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74   ^(On windows, t
28c00 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
28c10 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
28c20 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
28c30 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
28c40 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
28c50 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )^.**.** [[core 
28c60 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
28c70 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
28c80 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
28c90 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
28ca0 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
28cb0 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
28cc0 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
28cd0 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
28ce0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
28cf0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
28d00 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
28d10 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c  ite and its buil
28d20 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74  t-in [VFSes] int
28d30 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f  erpret the.** fo
28d40 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61  llowing query pa
28d50 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
28d60 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
28d70 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
28d80 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
28d90 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
28da0 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
28db0 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
28dc0 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
28dd0 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
28de0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
28df0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
28e00 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
28e10 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
28e20 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
28e30 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
28e40 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
28e50 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
28e60 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
28e70 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
28e80 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
28e90 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
28ea0 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
28eb0 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
28ec0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
28ed0 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
28ee0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
28ef0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
28f00 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
28f10 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
28f20 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
28f30 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
28f40 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
28f50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28f60 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
28f70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
28f80 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
28f90 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
28fa0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
28fb0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
28fc0 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
28fd0 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
28fe0 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
28ff0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
29000 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
29010 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
29020 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
29030 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
29040 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
29050 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
29060 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
29070 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
29080 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
29090 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
290a0 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
290b0 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
290c0 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
290d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
290e0 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
290f0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
29100 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
29110 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
29120 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
29130 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
29140 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
29150 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
29160 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
29170 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
29180 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
29190 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
291a0 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
291b0 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
291c0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
291d0 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
291e0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
291f0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
29200 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
29210 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
29220 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
29230 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
29240 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
29250 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
29260 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
29270 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
29280 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
29290 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
292a0 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
292b0 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
292c0 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
292d0 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
292e0 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
292f0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
29300 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
29310 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
29320 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
29330 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
29340 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
29350 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
29360 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
29370 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
29380 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
29390 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
293a0 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
293b0 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
293c0 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
293d0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
293e0 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
293f0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
29400 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
29410 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
29420 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
29430 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
29440 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
29450 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
29460 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
29470 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
29480 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
29490 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
294a0 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
294b0 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
294c0 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
294d0 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
294e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
294f0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
29500 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
29510 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
29520 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
29530 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
29540 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
29550 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
29560 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
29570 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
29580 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c   flag..**.**  <l
29590 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20  i> <b>psow</b>: 
295a0 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65  ^The psow parame
295b0 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68  ter indicates wh
295c0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
295d0 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61  .**     [powersa
295e0 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72  fe overwrite] pr
295f0 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64  operty does or d
29600 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f  oes not apply to
29610 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72   the.**     stor
29620 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69  age media on whi
29630 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
29640 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a  file resides..**
29650 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c  .**  <li> <b>nol
29660 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f  ock</b>: ^The no
29670 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  lock parameter i
29680 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
29690 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  y parameter.**  
296a0 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20     which if set 
296b0 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f  disables file lo
296c0 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63  cking in rollbac
296d0 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e  k journal modes.
296e0 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73    This.**     is
296f0 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65   useful for acce
29700 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  ssing a database
29710 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d   on a filesystem
29720 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a   that does not.*
29730 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f  *     support lo
29740 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a  cking.  Caution:
29750 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75    Database corru
29760 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75  ption might resu
29770 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20  lt if two.**    
29780 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73   or more process
29790 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20  es write to the 
297a0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e  same database an
297b0 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f  d any one of tho
297c0 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73  se.**     proces
297d0 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d  ses uses nolock=
297e0 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  1..**.**  <li> <
297f0 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a  b>immutable</b>:
29800 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20   ^The immutable 
29810 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
29820 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20  oolean query.** 
29830 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68      parameter th
29840 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  at indicates tha
29850 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  t the database f
29860 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e  ile is stored on
29870 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c  .**     read-onl
29880 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20  y media.  ^When 
29890 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74  immutable is set
298a0 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
298b0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
298c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63   database file c
298d0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
298e0 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63  , even by a proc
298f0 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a  ess with higher.
29900 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65  **     privilege
29910 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74  , and so the dat
29920 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
29930 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c  read-only and al
29940 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20  l locking.**    
29950 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65   and change dete
29960 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65  ction is disable
29970 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74  d.  Caution: Set
29980 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62  ting the immutab
29990 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72  le.**     proper
299a0 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ty on a database
299b0 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20   file that does 
299c0 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63  in fact change c
299d0 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20  an result.**    
299e0 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75   in incorrect qu
299f0 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f  ery results and/
29a00 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  or [SQLITE_CORRU
29a10 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20  PT] errors..**  
29a20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51     See also: [SQ
29a30 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
29a40 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20  ABLE]..**       
29a50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
29a60 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
29a70 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
29a80 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
29a90 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
29aa0 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
29ab0 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
29ac0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
29ad0 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
29ae0 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
29af0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
29b00 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
29b10 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
29b20 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
29b30 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
29b40 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
29b50 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
29b60 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
29b70 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
29b80 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
29b90 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
29ba0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
29bb0 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
29bc0 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
29bd0 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
29be0 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
29bf0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
29c00 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
29c10 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
29c20 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
29c30 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
29c40 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
29c50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
29c60 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
29c70 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
29c80 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
29c90 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
29ca0 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
29cb0 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
29cc0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
29cd0 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
29ce0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
29cf0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
29d00 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
29d10 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
29d20 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
29d30 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
29d40 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
29d50 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
29d60 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
29d70 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
29d80 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
29d90 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
29da0 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
29db0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
29dc0 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
29dd0 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
29de0 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
29df0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
29e00 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
29e10 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
29e20 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
29e30 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
29e40 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
29e50 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
29e60 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
29e70 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
29e80 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
29e90 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
29ea0 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
29eb0 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
29ec0 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
29ed0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
29ee0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
29ef0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
29f00 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
29f10 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
29f20 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
29f30 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
29f40 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
29f50 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
29f60 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
29f70 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
29f80 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
29f90 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
29fa0 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
29fb0 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
29fc0 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
29fd0 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
29fe0 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
29ff0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
2a000 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
2a010 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e  nix-dotfile <td>
2a020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
2a030 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
2a040 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
2a050 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
2a060 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a   "unix-dotfile".
2a070 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
2a080 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20   uses dot-files 
2a090 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69  in place of posi
2a0a0 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69  x advisory locki
2a0b0 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ng..** <tr><td> 
2a0c0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
2a0d0 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
2a0e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
2a0f0 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
2a100 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
2a110 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
2a120 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
2a130 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
2a140 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
2a150 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
2a160 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
2a170 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
2a180 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
2a190 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
2a1a0 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
2a1b0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
2a1c0 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
2a1d0 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
2a1e0 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
2a1f0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
2a200 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
2a210 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
2a220 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
2a230 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
2a240 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
2a250 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
2a260 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
2a270 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
2a280 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
2a290 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
2a2a0 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
2a2b0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
2a2c0 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
2a2d0 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
2a2e0 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
2a2f0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
2a300 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
2a310 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
2a320 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
2a330 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
2a340 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
2a350 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2a360 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
2a370 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
2a380 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
2a390 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
2a3a0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
2a3b0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
2a3c0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
2a3d0 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
2a3e0 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
2a3f0 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
2a400 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
2a410 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
2a420 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
2a430 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
2a440 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
2a450 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
2a460 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
2a470 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
2a480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
2a490 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
2a4a0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
2a4b0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
2a4c0 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
2a4d0 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
2a4e0 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
2a4f0 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
2a500 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
2a510 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
2a520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2a530 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
2a540 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
2a550 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
2a560 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
2a570 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
2a580 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
2a590 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
2a5a0 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
2a5b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
2a5c0 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
2a5d0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
2a5e0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
2a5f0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
2a600 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
2a610 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
2a620 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
2a630 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2a640 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
2a650 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
2a660 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
2a670 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
2a680 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
2a690 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
2a6a0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
2a6b0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
2a6c0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
2a6d0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
2a6e0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
2a6f0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
2a700 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
2a710 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
2a720 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
2a730 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
2a740 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
2a750 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2a760 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
2a770 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
2a780 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
2a790 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
2a7a0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
2a7b0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
2a7c0 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
2a7d0 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
2a7e0 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
2a7f0 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
2a800 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
2a810 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
2a820 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
2a830 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
2a840 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
2a850 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
2a860 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
2a870 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
2a880 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
2a890 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
2a8a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
2a8b0 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
2a8c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
2a8d0 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
2a8e0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
2a8f0 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
2a900 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
2a910 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
2a920 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
2a930 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
2a940 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
2a950 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
2a960 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
2a970 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
2a980 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
2a990 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
2a9a0 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
2a9b0 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
2a9c0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
2a9d0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
2a9e0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2a9f0 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
2aa00 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
2aa10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2aa20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
2aa30 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
2aa40 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
2aa50 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
2aa60 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
2aa70 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
2aa80 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
2aa90 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
2aaa0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
2aab0 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
2aac0 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
2aad0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
2aae0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
2aaf0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
2ab00 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
2ab10 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
2ab20 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
2ab30 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
2ab40 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
2ab50 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
2ab60 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
2ab70 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
2ab80 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
2ab90 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2aba0 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
2abb0 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
2abc0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
2abd0 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
2abe0 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
2abf0 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
2ac00 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
2ac10 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
2ac20 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
2ac30 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
2ac40 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
2ac50 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
2ac60 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
2ac70 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
2ac80 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
2ac90 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
2aca0 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
2acb0 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
2acc0 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
2acd0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
2ace0 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
2acf0 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
2ad00 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
2ad10 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
2ad20 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
2ad30 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
2ad40 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
2ad50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
2ad60 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
2ad70 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
2ad80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2ad90 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
2ada0 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
2adb0 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
2adc0 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
2add0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2ade0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
2adf0 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
2ae00 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
2ae10 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
2ae20 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
2ae30 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2ae40 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
2ae50 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
2ae60 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
2ae70 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
2ae80 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
2ae90 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
2aea0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
2aeb0 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
2aec0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
2aed0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
2aee0 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
2aef0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2af00 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
2af10 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
2af20 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
2af30 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
2af40 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
2af50 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
2af60 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2af70 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
2af80 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
2af90 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
2afa0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
2afb0 2a 20 53 65 65 20 74 68 65 20 5b 55 52 49 20 66  * See the [URI f
2afc0 69 6c 65 6e 61 6d 65 5d 20 64 6f 63 75 6d 65 6e  ilename] documen
2afd0 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
2afe0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
2aff0 6e 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  n..*/.const char
2b000 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
2b010 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
2b020 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
2b030 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
2b040 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
2b050 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
2b060 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
2b070 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
2b080 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
2b090 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2b0a0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
2b0b0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
2b0c0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
2b0d0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
2b0e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
2b0f0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
2b100 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ssages.** METHOD
2b110 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
2b120 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2b130 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ent sqlite3_* AP
2b140 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
2b150 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61  d with .** [data
2b160 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b170 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20   D failed, then 
2b180 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  the sqlite3_errc
2b190 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65  ode(D) interface
2b1a0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
2b1b0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
2b1c0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
2b1d0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
2b1e0 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20  for that.** API 
2b1f0 63 61 6c 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  call..** ^The sq
2b200 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
2b210 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
2b220 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
2b230 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
2b240 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2b250 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
2b260 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
2b270 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
2b280 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
2b290 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
2b2a0 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73  **.** The values
2b2b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2b2c0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 61  ite3_errcode() a
2b2d0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2b2e0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
2b2f0 65 28 29 20 6d 69 67 68 74 20 63 68 61 6e 67 65  e() might change
2b300 20 77 69 74 68 20 65 61 63 68 20 41 50 49 20 63   with each API c
2b310 61 6c 6c 2e 0a 2a 2a 20 45 78 63 65 70 74 2c 20  all..** Except, 
2b320 74 68 65 72 65 20 61 72 65 20 73 6f 6d 65 20 69  there are some i
2b330 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61  nterfaces that a
2b340 72 65 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  re guaranteed to
2b350 20 6e 65 76 65 72 0a 2a 2a 20 63 68 61 6e 67 65   never.** change
2b360 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2b370 65 20 65 72 72 6f 72 20 63 6f 64 65 2e 20 20 54  e error code.  T
2b380 68 65 20 65 72 72 6f 72 2d 63 6f 64 65 20 70 72  he error-code pr
2b390 65 73 65 72 76 69 6e 67 0a 2a 2a 20 69 6e 74 65  eserving.** inte
2b3a0 72 66 61 63 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a  rfaces are:.**.*
2b3b0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73  * <ul>.** <li> s
2b3c0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
2b3d0 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33  .** <li> sqlite3
2b3e0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
2b3f0 65 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  e().** <li> sqli
2b400 74 65 33 5f 65 72 72 6d 73 67 28 29 0a 2a 2a 20  te3_errmsg().** 
2b410 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72  <li> sqlite3_err
2b420 6d 73 67 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e  msg16().** </ul>
2b430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b440 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
2b450 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
2b460 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
2b470 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
2b480 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
2b490 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
2b4a0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
2b4b0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
2b4c0 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
2b4d0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
2b4e0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
2b4f0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
2b500 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
2b510 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
2b520 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
2b530 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
2b540 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
2b550 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
2b560 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
2b570 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
2b580 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
2b590 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
2b5a0 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
2b5b0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
2b5c0 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
2b5d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b5e0 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61  errstr() interfa
2b5f0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45  ce returns the E
2b600 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
2b610 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73  text.** that des
2b620 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75  cribes the [resu
2b630 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46  lt code], as UTF
2b640 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  -8..** ^(Memory 
2b650 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
2b660 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
2b670 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
2b680 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75  rnally.** and mu
2b690 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20  st not be freed 
2b6a0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
2b6b0 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  on)^..**.** When
2b6c0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
2b6d0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
2b6e0 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
2b6f0 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
2b700 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
2b710 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
2b720 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
2b730 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
2b740 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
2b750 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
2b760 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
2b770 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
2b780 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
2b790 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
2b7a0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
2b7b0 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
2b7c0 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
2b7d0 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
2b7e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2b7f0 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
2b800 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
2b810 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
2b820 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
2b830 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
2b840 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
2b850 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
2b860 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
2b870 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
2b880 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
2b890 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
2b8a0 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
2b8b0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
2b8c0 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
2b8d0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
2b8e0 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
2b8f0 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
2b900 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
2b910 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
2b920 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
2b930 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
2b940 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
2b950 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
2b960 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
2b970 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
2b980 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
2b990 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
2b9a0 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
2b9b0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
2b9c0 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
2b9d0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
2b9e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
2b9f0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
2ba00 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
2ba10 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
2ba20 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
2ba30 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2ba40 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
2ba50 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2ba60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
2ba70 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
2ba80 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ba90 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a  errstr(int);../*
2baa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72  .** CAPI3REF: Pr
2bab0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2bac0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
2bad0 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
2bae0 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
2baf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
2bb00 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
2bb10 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
2bb20 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
2bb30 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
2bb40 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62  nt that.** has b
2bb50 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74  een compiled int
2bb60 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e  o binary form an
2bb70 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  d is ready to be
2bb80 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a   evaluated..**.*
2bb90 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20  * Think of each 
2bba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
2bbb0 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70   a separate comp
2bbc0 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54  uter program.  T
2bbd0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
2bbe0 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63  QL text is sourc
2bbf0 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61  e code.  A prepa
2bc00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
2bc10 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20  ject .** is the 
2bc20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20  compiled object 
2bc30 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d  code.  All SQL m
2bc40 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2bc50 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61   into a.** prepa
2bc60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65  red statement be
2bc70 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72  fore it can be r
2bc80 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  un..**.** The li
2bc90 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72  fe-cycle of a pr
2bca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bcb0 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20   object usually 
2bcc0 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a  goes like this:.
2bcd0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2bce0 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72  i> Create the pr
2bcf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bd00 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
2bd10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bd20 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  2()]..** <li> Bi
2bd30 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61  nd values to [pa
2bd40 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
2bd50 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2bd60 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
2bd70 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
2bd80 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
2bd90 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2bda0 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
2bdb0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
2bdc0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72  li> Reset the pr
2bdd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bde0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2bdf0 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
2be00 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
2be10 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
2be20 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
2be30 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
2be40 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
2be50 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2be60 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
2be70 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66  </ol>.*/.typedef
2be80 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2be90 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
2bea0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
2beb0 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
2bec0 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  its.** METHOD: s
2bed0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54  qlite3.**.** ^(T
2bee0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
2bef0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
2bf00 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
2bf10 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
2bf20 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
2bf30 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
2bf40 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
2bf50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2bf60 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
2bf70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
2bf80 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
2bf90 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
2bfa0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
2bfb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2bfc0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
2bfd0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
2bfe0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
2bff0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
2c000 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
2c010 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
2c020 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2c030 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
2c040 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
2c050 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
2c060 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
2c070 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
2c080 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
2c090 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
2c0a0 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
2c0b0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
2c0c0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
2c0d0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
2c0e0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
2c0f0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
2c100 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
2c110 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
2c120 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
2c130 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
2c140 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
2c150 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
2c160 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
2c170 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
2c180 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
2c190 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
2c1a0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
2c1b0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
2c1c0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
2c1d0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
2c1e0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
2c1f0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
2c200 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
2c210 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
2c220 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
2c230 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
2c240 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
2c250 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
2c260 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
2c270 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
2c280 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
2c290 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
2c2a0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
2c2b0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
2c2c0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
2c2d0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
2c2e0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
2c2f0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2c300 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
2c310 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
2c320 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
2c330 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
2c340 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
2c350 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
2c360 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
2c370 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
2c380 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
2c390 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
2c3a0 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
2c3b0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
2c3c0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
2c3d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
2c3e0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
2c3f0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
2c400 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
2c410 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
2c420 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
2c430 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
2c440 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
2c450 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
2c460 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
2c470 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
2c480 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
2c490 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
2c4a0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
2c4b0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
2c4c0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
2c4d0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
2c4e0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
2c4f0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
2c500 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
2c510 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
2c520 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
2c530 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
2c540 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
2c550 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
2c560 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
2c570 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
2c580 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
2c590 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
2c5a0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
2c5b0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
2c5c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2c5d0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
2c5e0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
2c5f0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
2c600 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
2c610 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
2c620 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
2c630 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
2c640 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
2c650 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
2c660 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
2c670 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c680 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
2c690 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
2c6a0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
2c6b0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
2c6c0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
2c6d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
2c6e0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
2c6f0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
2c700 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
2c710 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
2c720 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
2c730 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
2c740 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
2c750 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
2c760 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
2c770 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
2c780 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
2c790 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
2c7a0 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
2c7b0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
2c7c0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2c7d0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
2c7e0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
2c7f0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
2c800 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
2c810 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2c820 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
2c830 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2c840 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2c850 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
2c860 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
2c870 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
2c880 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
2c890 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2c8a0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2c8b0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
2c8c0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2c8d0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2c8e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
2c8f0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
2c900 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
2c910 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2c920 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
2c930 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
2c940 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2c950 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2c960 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2c970 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2c980 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
2c990 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
2c9a0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2c9b0 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
2c9c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2c9d0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
2c9e0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
2c9f0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
2ca00 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
2ca10 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2ca20 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2ca30 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
2ca40 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2ca50 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
2ca60 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
2ca70 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
2ca80 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
2ca90 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
2caa0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2cab0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2cac0 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
2cad0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
2cae0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
2caf0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2cb00 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
2cb10 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
2cb20 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
2cb30 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2cb40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
2cb50 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
2cb60 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
2cb70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2cb80 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2cb90 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
2cba0 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
2cbb0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
2cbc0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
2cbd0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
2cbe0 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33  nt.  If [sqlite3
2cbf0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2cc00 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c  r.** the equival
2cc10 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c  ent tries to all
2cc20 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 20  ocate space for 
2cc30 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d  more than this m
2cc40 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69  any opcodes.** i
2cc50 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61  n a single prepa
2cc60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61  red statement, a
2cc70 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65  n SQLITE_NOMEM e
2cc80 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
2cc90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2cca0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
2ccb0 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
2ccc0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2ccd0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
2cce0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2ccf0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
2cd00 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
2cd10 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
2cd20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2cd30 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
2cd40 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2cd50 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
2cd60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2cd70 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
2cd80 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
2cd90 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
2cda0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
2cdb0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
2cdc0 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
2cdd0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2cde0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2cdf0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
2ce00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2ce10 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
2ce20 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
2ce30 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
2ce40 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
2ce50 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
2ce60 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2ce70 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2ce80 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
2ce90 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2cea0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
2ceb0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2cec0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
2ced0 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
2cee0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
2cef0 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
2cf00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
2cf10 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
2cf20 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2cf30 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
2cf40 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2cf50 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
2cf60 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
2cf70 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
2cf80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2cf90 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2cfa0 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  S]] ^(<dt>SQLITE
2cfb0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
2cfc0 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  READS</dt>.** <d
2cfd0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2cfe0 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72  mber of auxiliar
2cff0 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73  y worker threads
2d000 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a   that a single.*
2d010 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2d020 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74  ement] may start
2d030 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
2d040 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
2d050 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2d060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d070 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
2d080 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
2d090 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
2d0a0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
2d0b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
2d0c0 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
2d0d0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
2d0e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
2d0f0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
2d100 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
2d110 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
2d120 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
2d130 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
2d140 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
2d150 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
2d160 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
2d170 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2d180 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
2d190 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
2d1a0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2d1b0 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
2d1c0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
2d1d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2d1e0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
2d1f0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
2d200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2d210 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2d220 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
2d230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2d240 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
2d250 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
2d260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2d270 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2d280 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31  ADS           11
2d290 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d2a0 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a  : Prepare Flags.
2d2b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2d2c0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
2d2d0 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74 20  ious flags that 
2d2e0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e  can be passed in
2d2f0 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73  to.** "prepFlags
2d300 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  " parameter of t
2d310 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
2d320 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a  are_v3()] and.**
2d330 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d340 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66  e16_v3()] interf
2d350 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  aces..**.** New 
2d360 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64 64  flags may be add
2d370 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
2d380 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2d390 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
2d3a0 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  [SQLITE_PREPARE_
2d3b0 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c  PERSISTENT]] ^(<
2d3c0 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52  dt>SQLITE_PREPAR
2d3d0 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74  E_PERSISTENT</dt
2d3e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  >.** <dd>The SQL
2d3f0 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2d400 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61  ISTENT flag is a
2d410 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65   hint to the que
2d420 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68  ry planner.** th
2d430 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
2d440 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
2d450 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61  e retained for a
2d460 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a   long time and.*
2d470 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65  * probably reuse
2d480 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20  d many times.)^ 
2d490 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c  ^Without this fl
2d4a0 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ag, [sqlite3_pre
2d4b0 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e  pare_v3()].** an
2d4c0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2d4d0 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d  re16_v3()] assum
2d4e0 65 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61  e that the prepa
2d4f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69  red statement wi
2d500 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a  ll .** be used j
2d510 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d  ust once or at m
2d520 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65 73 20  ost a few times 
2d530 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79  and then destroy
2d540 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2d550 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2d560 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e   relatively soon
2d570 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d  . The current im
2d580 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74  plementation act
2d590 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e  s.** on this hin
2d5a0 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68  t by avoiding th
2d5b0 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73  e use of [lookas
2d5c0 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61  ide memory] so a
2d5d0 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c  s not to.** depl
2d5e0 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20  ete the limited 
2d5f0 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69  store of lookasi
2d600 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72  de memory. Futur
2d610 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a  e versions of.**
2d620 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20   SQLite may act 
2d630 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69 66  on this hint dif
2d640 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ferently..**.** 
2d650 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  [[SQLITE_PREPARE
2d660 5f 4e 4f 52 4d 41 4c 49 5a 45 5d 5d 20 3c 64 74  _NORMALIZE]] <dt
2d670 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  >SQLITE_PREPARE_
2d680 4e 4f 52 4d 41 4c 49 5a 45 3c 2f 64 74 3e 0a 2a  NORMALIZE</dt>.*
2d690 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45  * <dd>The SQLITE
2d6a0 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49  _PREPARE_NORMALI
2d6b0 5a 45 20 66 6c 61 67 20 69 73 20 61 20 6e 6f 2d  ZE flag is a no-
2d6c0 6f 70 2e 20 54 68 69 73 20 66 6c 61 67 20 75 73  op. This flag us
2d6d0 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65 71 75  ed.** to be requ
2d6e0 69 72 65 64 20 66 6f 72 20 61 6e 79 20 70 72 65  ired for any pre
2d6f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2d700 74 68 61 74 20 77 61 6e 74 65 64 20 74 6f 20 75  that wanted to u
2d710 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
2d720 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71  e3_normalized_sq
2d730 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
2d740 20 48 6f 77 65 76 65 72 2c 20 74 68 65 0a 2a 2a   However, the.**
2d750 20 5b 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c   [sqlite3_normal
2d760 69 7a 65 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65  ized_sql()] inte
2d770 72 66 61 63 65 20 69 73 20 6e 6f 77 20 61 76 61  rface is now ava
2d780 69 6c 61 62 6c 65 20 74 6f 20 61 6c 6c 0a 2a 2a  ilable to all.**
2d790 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d7a0 65 6e 74 73 2c 20 72 65 67 61 72 64 6c 65 73 73  ents, regardless
2d7b0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
2d7c0 6f 74 20 74 68 65 79 20 75 73 65 20 74 68 69 73  ot they use this
2d7d0 0a 2a 2a 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20  .** flag..**.** 
2d7e0 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  [[SQLITE_PREPARE
2d7f0 5f 4e 4f 5f 56 54 41 42 5d 5d 20 3c 64 74 3e 53  _NO_VTAB]] <dt>S
2d800 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f  QLITE_PREPARE_NO
2d810 5f 56 54 41 42 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _VTAB</dt>.** <d
2d820 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45  d>The SQLITE_PRE
2d830 50 41 52 45 5f 4e 4f 5f 56 54 41 42 20 66 6c 61  PARE_NO_VTAB fla
2d840 67 20 63 61 75 73 65 73 20 74 68 65 20 53 51 4c  g causes the SQL
2d850 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20   compiler.** to 
2d860 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20  return an error 
2d870 28 65 72 72 6f 72 20 63 6f 64 65 20 53 51 4c 49  (error code SQLI
2d880 54 45 5f 45 52 52 4f 52 29 20 69 66 20 74 68 65  TE_ERROR) if the
2d890 20 73 74 61 74 65 6d 65 6e 74 20 75 73 65 73 0a   statement uses.
2d8a0 2a 2a 20 61 6e 79 20 76 69 72 74 75 61 6c 20 74  ** any virtual t
2d8b0 61 62 6c 65 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  ables..** </dl>.
2d8c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d8d0 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2d8e0 54 45 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  TENT            
2d8f0 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53    0x01.#define S
2d900 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f  QLITE_PREPARE_NO
2d910 52 4d 41 4c 49 5a 45 20 20 20 20 20 20 20 20 20  RMALIZE         
2d920 20 20 20 20 20 20 30 78 30 32 0a 23 64 65 66 69        0x02.#defi
2d930 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  ne SQLITE_PREPAR
2d940 45 5f 4e 4f 5f 56 54 41 42 20 20 20 20 20 20 20  E_NO_VTAB       
2d950 20 20 20 20 20 20 20 20 20 20 30 78 30 34 0a 0a            0x04..
2d960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d970 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
2d980 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
2d990 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
2d9a0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
2d9b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2d9c0 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  te3.** CONSTRUCT
2d9d0 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
2d9e0 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
2d9f0 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  e an SQL stateme
2da00 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  nt, it must firs
2da10 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
2da20 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
2da30 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
2da40 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
2da50 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f  tines.  Or, in o
2da60 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 73  ther words, thes
2da70 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2da80 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 20 66  e constructors f
2da90 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2daa0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
2dab0 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ct..**.** The pr
2dac0 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e 65 20  eferred routine 
2dad0 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c 69 74  to use is [sqlit
2dae0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2daf0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
2db00 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 69 6e  e3_prepare()] in
2db10 74 65 72 66 61 63 65 20 69 73 20 6c 65 67 61 63  terface is legac
2db20 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  y and should be 
2db30 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c  avoided..** [sql
2db40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2db50 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72 61 20  )] has an extra 
2db60 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70 74 69  "prepFlags" opti
2db70 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65 64 0a  on that is used.
2db80 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c 20 70  ** for special p
2db90 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  urposes..**.** T
2dba0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 55 54  he use of the UT
2dbb0 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73 20 69  F-8 interfaces i
2dbc0 73 20 70 72 65 66 65 72 72 65 64 2c 20 61 73 20  s preferred, as 
2dbd0 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74 6c 79  SQLite currently
2dbe0 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61 72  .** does all par
2dbf0 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46 2d 38  sing using UTF-8
2dc00 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e  .  The UTF-16 in
2dc10 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
2dc20 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f  vided.** as a co
2dc30 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68 65 20  nvenience.  The 
2dc40 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65  UTF-16 interface
2dc50 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72  s work by conver
2dc60 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75  ting the.** inpu
2dc70 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54 46 2d  t text into UTF-
2dc80 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67  8, then invoking
2dc90 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2dca0 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61  ng UTF-8 interfa
2dcb0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ce..**.** The fi
2dcc0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
2dcd0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
2dce0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
2dcf0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
2dd00 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
2dd10 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2dd20 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2dd30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2dd40 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2dd50 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
2dd60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2dd70 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
2dd80 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
2dd90 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
2dda0 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
2ddb0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
2ddc0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2ddd0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
2dde0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
2ddf0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
2de00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 2c  lite3_prepare(),
2de10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2de20 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71  _v2(),.** and sq
2de30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2de40 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
2de50 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
2de60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2de70 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  6(), sqlite3_pre
2de80 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20  pare16_v2(),.** 
2de90 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2dea0 61 72 65 31 36 5f 76 33 28 29 20 75 73 65 20 55  are16_v3() use U
2deb0 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
2dec0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
2ded0 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ent is negative,
2dee0 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
2def0 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
2df00 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2df10 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
2df20 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
2df30 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20  en it is the.** 
2df40 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2df50 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
2df60 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65   ^If nByte is ze
2df70 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70  ro, then no prep
2df80 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2df90 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a  t is generated..
2dfa0 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  ** If the caller
2dfb0 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20   knows that the 
2dfc0 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
2dfd0 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
2dfe0 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65  d, then.** there
2dff0 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66   is a small perf
2e000 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
2e010 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20  e to passing an 
2e020 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
2e030 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e  that.** is the n
2e040 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2e050 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
2e060 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
2e070 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
2e080 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
2e090 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
2e0a0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
2e0b0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
2e0c0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
2e0d0 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
2e0e0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
2e0f0 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
2e100 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
2e110 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
2e120 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
2e130 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
2e140 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
2e150 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
2e160 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
2e170 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
2e180 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
2e190 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
2e1a0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
2e1b0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
2e1c0 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
2e1d0 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
2e1e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
2e1f0 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
2e200 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
2e210 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
2e220 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
2e230 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
2e240 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
2e250 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
2e260 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
2e270 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
2e280 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
2e290 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
2e2a0 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
2e2b0 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
2e2c0 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
2e2d0 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
2e2e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
2e2f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2e300 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
2e310 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
2e320 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
2e330 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
2e340 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
2e350 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
2e360 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
2e370 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
2e380 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2e390 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
2e3a0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
2e3b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
2e3c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2e3d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c 20 73  _prepare_v2(), s
2e3e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e3f0 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  3(), sqlite3_pre
2e400 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20  pare16_v2(),.** 
2e410 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2e420 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74 65 72  are16_v3() inter
2e430 66 61 63 65 73 20 61 72 65 20 72 65 63 6f 6d 6d  faces are recomm
2e440 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
2e450 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54  w programs..** T
2e460 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  he older interfa
2e470 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70 72 65  ces (sqlite3_pre
2e480 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
2e490 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 29 0a  e3_prepare16()).
2e4a0 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ** are retained 
2e4b0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
2e4c0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
2e4d0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
2e4e0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
2e4f0 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72  n the "vX" inter
2e500 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
2e510 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2e520 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
2e530 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2e540 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
2e550 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
2e560 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
2e570 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
2e580 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
2e590 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
2e5a0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
2e5b0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
2e5c0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
2e5d0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2e5e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
2e5f0 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
2e600 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
2e610 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2e620 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
2e630 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
2e640 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
2e650 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
2e660 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2e670 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
2e680 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
2e690 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
2e6a0 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
2e6b0 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
2e6c0 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
2e6d0 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
2e6e0 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
2e6f0 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
2e700 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
2e710 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2e720 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
2e730 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
2e740 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2e750 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
2e760 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
2e770 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
2e780 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
2e790 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
2e7a0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2e7b0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
2e7c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e7d0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
2e7e0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
2e7f0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
2e800 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
2e810 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
2e820 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
2e830 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
2e840 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2e850 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
2e860 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
2e870 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
2e880 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
2e890 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
2e8a0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
2e8b0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
2e8c0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
2e8d0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2e8e0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
2e8f0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2e900 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
2e910 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
2e920 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
2e930 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
2e940 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
2e950 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
2e960 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
2e970 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2e980 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
2e990 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
2e9a0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2e9b0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
2e9c0 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
2e9d0 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
2e9e0 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
2e9f0 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
2ea00 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
2ea10 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
2ea20 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
2ea30 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
2ea40 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
2ea50 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
2ea60 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
2ea70 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
2ea80 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
2ea90 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
2eaa0 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
2eab0 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
2eac0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
2ead0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2eae0 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
2eaf0 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
2eb00 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
2eb10 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
2eb20 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
2eb30 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
2eb40 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
2eb50 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
2eb60 45 4e 41 42 4c 45 5f 53 54 41 54 34 5d 20 63 6f  ENABLE_STAT4] co
2eb70 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2eb80 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
2eb90 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
2eba0 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65  **.** <p>^sqlite
2ebb0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 64  3_prepare_v3() d
2ebc0 69 66 66 65 72 73 20 66 72 6f 6d 20 73 71 6c 69  iffers from sqli
2ebd0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2ebe0 20 6f 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a   only in having.
2ebf0 2a 2a 20 74 68 65 20 65 78 74 72 61 20 70 72 65  ** the extra pre
2ec00 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72  pFlags parameter
2ec10 2c 20 77 68 69 63 68 20 69 73 20 61 20 62 69 74  , which is a bit
2ec20 20 61 72 72 61 79 20 63 6f 6e 73 69 73 74 69 6e   array consistin
2ec30 67 20 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  g of zero or.** 
2ec40 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
2ec50 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2ec60 49 53 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52  ISTENT|SQLITE_PR
2ec70 45 50 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20  EPARE_*] flags. 
2ec80 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
2ec90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 69 6e  _prepare_v2() in
2eca0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 65 78  terface works ex
2ecb0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
2ecc0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
2ecd0 70 61 72 65 5f 76 33 28 29 20 77 69 74 68 20 61  pare_v3() with a
2ece0 20 7a 65 72 6f 20 70 72 65 70 46 6c 61 67 73 20   zero prepFlags 
2ecf0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e  parameter..*/.in
2ed00 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2ed10 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2ed20 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2ed30 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2ed40 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2ed50 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2ed60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2ed70 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2ed80 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2ed90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2eda0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2edb0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2edc0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2edd0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2ede0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2edf0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2ee00 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2ee10 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2ee20 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2ee30 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2ee40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2ee50 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
2ee60 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2ee70 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2ee80 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2ee90 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2eea0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2eeb0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2eec0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2eed0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2eee0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2eef0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2ef00 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2ef10 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2ef20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2ef30 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2ef40 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2ef50 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2ef60 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2ef70 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2ef80 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2ef90 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 0a 20  e3_prepare_v3(. 
2efa0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2efb0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2efc0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2efd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2efe0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2eff0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2f000 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2f010 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2f020 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2f030 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2f040 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75  in bytes. */.  u
2f050 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70  nsigned int prep
2f060 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f  Flags, /* Zero o
2f070 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52  r more SQLITE_PR
2f080 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a  EPARE_ flags */.
2f090 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2f0a0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2f0b0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2f0c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2f0d0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2f0e0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2f0f0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2f100 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2f110 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2f120 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
2f130 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2f140 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2f150 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2f160 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2f170 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2f180 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2f190 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2f1a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2f1b0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2f1c0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2f1d0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2f1e0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2f1f0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2f200 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2f210 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2f220 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2f230 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2f240 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2f250 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2f260 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
2f270 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2f280 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2f290 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2f2a0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2f2b0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2f2c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2f2d0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2f2e0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2f2f0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2f300 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2f310 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2f320 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2f330 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2f340 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2f350 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2f360 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2f370 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2f380 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2f390 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2f3a0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2f3b0 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c 69 74  re16_v3(.  sqlit
2f3c0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2f3d0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2f3e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2f3f0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2f400 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2f410 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2f420 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2f430 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2f440 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2f450 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2f460 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e  tes. */.  unsign
2f470 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73  ed int prepFlags
2f480 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72  , /* Zero or mor
2f490 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2f4a0 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c  _ flags */.  sql
2f4b0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2f4c0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2f4d0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2f4e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2f4f0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2f500 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2f510 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2f520 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
2f530 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
2f540 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
2f550 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   SQL.** METHOD: 
2f560 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2f570 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f580 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2f590 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2f5a0 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20  er to a copy of 
2f5b0 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c  the UTF-8.** SQL
2f5c0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
2f5d0 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73  eate [prepared s
2f5e0 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50  tatement] P if P
2f5f0 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20   was.** created 
2f600 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
2f610 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2f620 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2f630 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
2f640 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20  repare16_v2()], 
2f650 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2f660 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20  are16_v3()]..** 
2f670 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70  ^The sqlite3_exp
2f680 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74  anded_sql(P) int
2f690 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2f6a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54   pointer to a UT
2f6b0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  F-8.** string co
2f6c0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c  ntaining the SQL
2f6d0 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65   text of prepare
2f6e0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69  d statement P wi
2f6f0 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72  th.** [bound par
2f700 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65  ameters] expande
2f710 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
2f720 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71  e3_normalized_sq
2f730 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  l(P) interface r
2f740 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2f750 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73   to a UTF-8.** s
2f760 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
2f770 20 74 68 65 20 6e 6f 72 6d 61 6c 69 7a 65 64 20   the normalized 
2f780 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70  SQL text of prep
2f790 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2f7a0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 6d 61 6e 74  .  The.** semant
2f7b0 69 63 73 20 75 73 65 64 20 74 6f 20 6e 6f 72 6d  ics used to norm
2f7c0 61 6c 69 7a 65 20 61 20 53 51 4c 20 73 74 61 74  alize a SQL stat
2f7d0 65 6d 65 6e 74 20 61 72 65 20 75 6e 73 70 65 63  ement are unspec
2f7e0 69 66 69 65 64 20 61 6e 64 20 73 75 62 6a 65 63  ified and subjec
2f7f0 74 0a 2a 2a 20 74 6f 20 63 68 61 6e 67 65 2e 20  t.** to change. 
2f800 20 41 74 20 61 20 6d 69 6e 69 6d 75 6d 2c 20 6c   At a minimum, l
2f810 69 74 65 72 61 6c 20 76 61 6c 75 65 73 20 77 69  iteral values wi
2f820 6c 6c 20 62 65 20 72 65 70 6c 61 63 65 64 20 77  ll be replaced w
2f830 69 74 68 20 73 75 69 74 61 62 6c 65 0a 2a 2a 20  ith suitable.** 
2f840 70 6c 61 63 65 68 6f 6c 64 65 72 73 2e 0a 2a 2a  placeholders..**
2f850 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2f860 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64  e, if a prepared
2f870 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72   statement is cr
2f880 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20  eated using the 
2f890 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c  SQL.** text "SEL
2f8a0 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61  ECT $abc,:xyz" a
2f8b0 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20  nd if parameter 
2f8c0 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f  $abc is bound to
2f8d0 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a   integer 2345.**
2f8e0 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a   and parameter :
2f8f0 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20  xyz is unbound, 
2f900 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c  then sqlite3_sql
2f910 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  () will return.*
2f920 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
2f930 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24  tring, "SELECT $
2f940 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71  abc,:xyz" but sq
2f950 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2f960 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  ql().** will ret
2f970 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35  urn "SELECT 2345
2f980 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ,NULL".)^.**.** 
2f990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70  ^The sqlite3_exp
2f9a0 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65  anded_sql() inte
2f9b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55  rface returns NU
2f9c0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
2f9d0 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20  nt memory.** is 
2f9e0 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c  available to hol
2f9f0 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72  d the result, or
2fa00 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77   if the result w
2fa10 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a  ould exceed the.
2fa20 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  ** the maximum s
2fa30 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74  tring length det
2fa40 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b  ermined by the [
2fa50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2fa60 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  GTH]..**.** ^The
2fa70 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
2fa80 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
2fa90 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c  le-time option l
2faa0 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
2fab0 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d  f.** bound param
2fac0 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e  eter expansions.
2fad0 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
2fae0 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  MIT_TRACE] compi
2faf0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
2fb00 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33  n causes sqlite3
2fb10 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20  _expanded_sql() 
2fb20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  to always return
2fb30 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
2fb40 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
2fb50 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71  ed by sqlite3_sq
2fb60 6c 28 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  l(P) and sqlite3
2fb70 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2fb80 50 29 0a 2a 2a 20 61 72 65 20 6d 61 6e 61 67 65  P).** are manage
2fb90 64 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20  d by SQLite and 
2fba0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
2fbb0 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65  y freed when the
2fbc0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2fbd0 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69  tement is finali
2fbe0 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72  zed..** ^The str
2fbf0 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
2fc00 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2fc10 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20  _sql(P), on the 
2fc20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69  other hand,.** i
2fc30 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
2fc40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2fc50 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66  )] and must be f
2fc60 72 65 65 20 62 79 20 74 68 65 20 61 70 70 6c 69  ree by the appli
2fc70 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73  cation.** by pas
2fc80 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
2fc90 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a  te3_free()]..*/.
2fca0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2fcb0 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
2fcc0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68  stmt *pStmt);.ch
2fcd0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61  ar *sqlite3_expa
2fce0 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33  nded_sql(sqlite3
2fcf0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63  _stmt *pStmt);.c
2fd00 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2fd10 65 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71  e3_normalized_sq
2fd20 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
2fd30 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2fd40 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2fd50 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
2fd60 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
2fd70 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45  e Database.** ME
2fd80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2fd90 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2fda0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2fdb0 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
2fdc0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2fdd0 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
2fde0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
2fdf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fe00 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
2fe10 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
2fe20 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
2fe30 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2fe40 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
2fe50 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
2fe60 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2fe70 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
2fe80 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
2fe90 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
2fea0 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
2feb0 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
2fec0 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
2fed0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2fee0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
2fef0 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
2ff00 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
2ff10 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
2ff20 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
2ff30 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
2ff40 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
2ff50 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
2ff60 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
2ff70 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
2ff80 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
2ff90 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
2ffa0 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
2ffb0 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
2ffc0 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
2ffd0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
2ffe0 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
2fff0 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
30000 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
30010 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
30020 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
30030 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
30040 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
30050 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
30060 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
30070 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
30080 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
30090 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
300a0 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
300b0 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
300c0 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
300d0 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
300e0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
300f0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
30100 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
30110 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
30120 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
30130 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
30140 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
30150 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
30160 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
30170 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
30180 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
30190 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
301a0 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
301b0 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
301c0 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
301d0 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
301e0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
301f0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
30200 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
30210 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
30220 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
30230 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
30240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30250 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
30260 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
30270 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
30280 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
30290 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a  iles on disk..**
302a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
302b0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e  mt_readonly() in
302c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
302d0 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d  true for [BEGIN]
302e0 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e   since.** [BEGIN
302f0 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e  ] merely sets in
30300 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75  ternal flags, bu
30310 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47  t the [BEGIN|BEG
30320 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e  IN IMMEDIATE] an
30330 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49  d.** [BEGIN|BEGI
30340 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d  N EXCLUSIVE] com
30350 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74  mands do touch t
30360 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
30370 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  so.** sqlite3_st
30380 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65  mt_readonly() re
30390 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20  turns false for 
303a0 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a  those commands..
303b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
303c0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
303d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
303e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
303f0 45 46 3a 20 51 75 65 72 79 20 54 68 65 20 45 58  EF: Query The EX
30400 50 4c 41 49 4e 20 53 65 74 74 69 6e 67 20 46 6f  PLAIN Setting Fo
30410 72 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  r A Prepared Sta
30420 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
30430 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30440 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30450 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e  3_stmt_isexplain
30460 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
30470 74 75 72 6e 73 20 31 20 69 66 20 74 68 65 0a 2a  turns 1 if the.*
30480 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
30490 6d 65 6e 74 20 53 20 69 73 20 61 6e 20 45 58 50  ment S is an EXP
304a0 4c 41 49 4e 20 73 74 61 74 65 6d 65 6e 74 2c 20  LAIN statement, 
304b0 6f 72 20 32 20 69 66 20 74 68 65 0a 2a 2a 20 73  or 2 if the.** s
304c0 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 61 6e  tatement S is an
304d0 20 45 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50   EXPLAIN QUERY P
304e0 4c 41 4e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  LAN..** ^The sql
304f0 69 74 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c  ite3_stmt_isexpl
30500 61 69 6e 28 53 29 20 69 6e 74 65 72 66 61 63 65  ain(S) interface
30510 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 53 20   returns 0 if S 
30520 69 73 0a 2a 2a 20 61 6e 20 6f 72 64 69 6e 61 72  is.** an ordinar
30530 79 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61  y statement or a
30540 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
30550 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
30560 6d 74 5f 69 73 65 78 70 6c 61 69 6e 28 73 71 6c  mt_isexplain(sql
30570 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
30580 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30590 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
305a0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
305b0 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
305c0 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eset.** METHOD: 
305d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
305e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
305f0 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
30600 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
30610 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
30620 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
30630 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
30640 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
30650 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
30660 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
30670 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
30680 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74  as neither run t
30690 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65  o completion (re
306a0 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
306b0 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71  E_DONE] from [sq
306c0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20  lite3_step(S)]) 
306d0 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  nor.** been rese
306e0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
306f0 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
30700 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
30710 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
30720 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
30730 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
30740 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
30750 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
30760 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
30770 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
30780 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
30790 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
307a0 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
307b0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
307c0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
307d0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
307e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
307f0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
30800 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
30810 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
30820 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
30830 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
30840 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
30850 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
30860 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
30870 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
30880 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
30890 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
308a0 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
308b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
308c0 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
308d0 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
308e0 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
308f0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
30900 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
30910 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
30920 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
30930 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
30940 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
30950 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
30960 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
30970 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
30980 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
30990 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
309a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
309b0 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
309c0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
309d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
309e0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
309f0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
30a00 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
30a10 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
30a20 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
30a30 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
30a40 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
30a50 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
30a60 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
30a70 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
30a80 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
30a90 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
30aa0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
30ab0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
30ac0 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
30ad0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
30ae0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
30af0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
30b00 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
30b10 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
30b20 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
30b30 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
30b40 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
30b50 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
30b60 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
30b70 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
30b80 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
30b90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30ba0 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
30bb0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
30bc0 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
30bd0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
30be0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
30bf0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
30c00 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
30c10 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68  lite3_value.  Th
30c20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  e.** [sqlite3_va
30c30 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72  lue_dup()] inter
30c40 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
30c50 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20   to construct a 
30c60 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65  new .** protecte
30c70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
30c80 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63  from an unprotec
30c90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30ca0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
30cb0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
30cc0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
30cd0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
30ce0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
30cf0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
30d00 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
30d10 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
30d20 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
30d30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
30d40 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
30d50 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
30d60 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
30d70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
30d80 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
30d90 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
30da0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
30db0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
30dc0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
30dd0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
30de0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
30df0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
30e00 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
30e10 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
30e20 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
30e30 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
30e40 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
30e50 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
30e60 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
30e70 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
30e80 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
30e90 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
30ea0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
30eb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
30ec0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
30ed0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
30ee0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
30ef0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
30f00 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
30f10 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
30f20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
30f30 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
30f40 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
30f50 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
30f60 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
30f70 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
30f80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
30f90 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
30fa0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
30fb0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
30fc0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
30fd0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
30fe0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
30ff0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
31000 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
31010 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
31020 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
31030 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
31040 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
31050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
31060 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
31070 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
31080 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
31090 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
310a0 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
310b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
310c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
310d0 65 64 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a  ed as arguments.
310e0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ** to [sqlite3_r
310f0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20  esult_value()], 
31100 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
31110 6c 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  lue()], and.** [
31120 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
31130 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  p()]..** The [sq
31140 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
31150 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
31160 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
31170 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
31180 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
31190 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
311a0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
311b0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
311c0 74 65 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65  te3_value sqlite
311d0 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
311e0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
311f0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
31200 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
31210 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
31220 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
31230 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
31240 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
31250 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
31260 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
31270 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
31280 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
31290 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
312a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
312b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
312c0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
312d0 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
312e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
312f0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
31300 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
31310 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
31320 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
31330 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
31340 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
31350 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
31360 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
31370 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31380 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
31390 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
313a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
313b0 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
313c0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
313d0 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
313e0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
313f0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
31400 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
31410 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
31420 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
31430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
31440 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
31450 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
31460 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
31470 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
31480 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
31490 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
314a0 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
314b0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
314c0 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
314d0 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
314e0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d  er binding}.** M
314f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31500 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  tmt.**.** ^(In t
31510 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
31520 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
31530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
31540 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
31550 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
31560 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
31570 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
31580 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
31590 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
315a0 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
315b0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
315c0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
315d0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
315e0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
315f0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
31600 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
31610 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
31620 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
31630 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
31640 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
31650 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
31660 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
31670 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
31680 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
31690 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
316a0 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
316b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
316c0 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
316d0 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
316e0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
316f0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
31700 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
31710 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
31720 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
31730 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
31740 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
31750 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
31760 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
31770 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
31780 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
31790 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
317a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
317b0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
317c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
317d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
317e0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
317f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
31800 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
31810 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
31820 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
31830 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
31840 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
31850 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
31860 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
31870 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
31880 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
31890 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
318a0 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
318b0 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
318c0 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
318d0 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
318e0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
318f0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
31900 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
31910 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
31920 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
31930 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
31940 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
31950 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
31960 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
31970 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
31980 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
31990 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
319a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
319b0 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
319c0 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
319d0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
319e0 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
319f0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
31a00 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
31a10 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
31a20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
31a30 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
31a40 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
31a50 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
31a60 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
31a70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
31a80 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
31a90 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
31aa0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
31ab0 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
31ac0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
31ad0 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
31ae0 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
31af0 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
31b00 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
31b10 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
31b20 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
31b30 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
31b40 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
31b50 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
31b60 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
31b70 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
31b80 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
31b90 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
31ba0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
31bb0 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
31bc0 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
31bd0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
31be0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
31bf0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
31c00 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
31c10 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
31c20 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
31c30 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
31c40 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
31c50 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
31c60 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
31c70 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
31c80 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
31c90 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
31ca0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
31cb0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
31cc0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
31cd0 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
31ce0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
31cf0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
31d00 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
31d10 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
31d20 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
31d30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
31d40 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
31d50 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
31d60 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
31d70 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a  text64() then.**
31d80 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
31d90 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
31da0 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
31db0 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
31dc0 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
31dd0 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
31de0 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
31df0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
31e00 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
31e10 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
31e20 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
31e30 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
31e40 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
31e50 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
31e60 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
31e70 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
31e80 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
31e90 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
31ea0 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
31eb0 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
31ec0 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
31ed0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
31ee0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
31ef0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
31f00 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61  nt to the BLOB a
31f10 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e  nd string bindin
31f20 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  g interfaces.** 
31f30 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
31f40 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
31f50 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
31f60 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
31f70 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
31f80 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
31f90 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
31fa0 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
31fb0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
31fc0 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
31fd0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  if the call to t
31fe0 68 65 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  he bind API fail
31ff0 73 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 65  s,.** except the
32000 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 6e   destructor is n
32010 6f 74 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65  ot called if the
32020 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
32030 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   is a NULL.** po
32040 69 6e 74 65 72 20 6f 72 20 74 68 65 20 66 6f 75  inter or the fou
32050 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
32060 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 20 5e 49   negative..** ^I
32070 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
32080 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
32090 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
320a0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
320b0 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
320c0 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
320d0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
320e0 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
320f0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
32100 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
32110 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
32120 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
32130 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
32140 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
32150 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
32160 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
32170 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
32180 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
32190 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
321a0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
321b0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
321c0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
321d0 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
321e0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
321f0 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65  text64() must be
32200 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49   one of.** [SQLI
32210 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
32220 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54  E_UTF16], [SQLIT
32230 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b  E_UTF16BE], or [
32240 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a  SQLITE_UTF16LE].
32250 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ** to specify th
32260 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68  e encoding of th
32270 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68  e text in the th
32280 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ird parameter.  
32290 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20  If.** the sixth 
322a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
322b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
322c0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
322d0 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76  the.** allowed v
322e0 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76  alues shown abov
322f0 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78  e, or if the tex
32300 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  t encoding is di
32310 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20  fferent.** from 
32320 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
32330 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69  cified by the si
32340 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74  xth parameter, t
32350 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
32360 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
32370 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32380 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
32390 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
323a0 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
323b0 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
323c0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
323d0 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
323e0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
323f0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
32400 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
32410 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
32420 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
32430 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
32440 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
32450 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
32460 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
32470 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
32480 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
32490 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
324a0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
324b0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
324c0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
324d0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
324e0 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
324f0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
32500 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
32510 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
32520 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  LOB..**.** ^The 
32530 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
32540 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20  nter(S,I,P,T,D) 
32550 72 6f 75 74 69 6e 65 20 63 61 75 73 65 73 20 74  routine causes t
32560 68 65 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65  he I-th paramete
32570 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65  r in.** [prepare
32580 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74  d statement] S t
32590 6f 20 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61  o have an SQL va
325a0 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74  lue of NULL, but
325b0 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61   to also be.** a
325c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
325d0 68 65 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20  he pointer P of 
325e0 74 79 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65  type T.  ^D is e
325f0 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
32600 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69  nter or.** a poi
32610 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75  nter to a destru
32620 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ctor function fo
32630 72 20 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c  r P. ^SQLite wil
32640 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20  l invoke the.** 
32650 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
32660 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  h a single argum
32670 65 6e 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74  ent of P when it
32680 20 69 73 20 66 69 6e 69 73 68 65 64 20 75 73 69   is finished usi
32690 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20  ng.** P.  The T 
326a0 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
326b0 20 62 65 20 61 20 73 74 61 74 69 63 20 73 74 72   be a static str
326c0 69 6e 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20  ing, preferably 
326d0 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65  a string.** lite
326e0 72 61 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33  ral. The sqlite3
326f0 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20  _bind_pointer() 
32700 72 6f 75 74 69 6e 65 20 69 73 20 70 61 72 74 20  routine is part 
32710 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74  of the.** [point
32720 65 72 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72  er passing inter
32730 66 61 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20  face] added for 
32740 53 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a  SQLite 3.20.0..*
32750 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
32760 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
32770 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
32780 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
32790 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
327a0 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
327b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
327c0 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
327d0 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
327e0 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
327f0 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
32800 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
32810 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
32820 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
32830 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
32840 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
32850 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
32860 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
32870 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
32880 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
32890 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
328a0 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
328b0 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
328c0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
328d0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
328e0 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
328f0 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
32900 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
32910 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32920 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
32930 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
32940 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
32950 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
32960 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
32970 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
32980 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
32990 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
329a0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
329b0 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
329c0 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
329d0 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d  SQLITE_TOOBIG] m
329e0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
329f0 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
32a00 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
32a10 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69  .** exceeds limi
32a20 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73  ts imposed by [s
32a30 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
32a40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
32a50 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  TH]) or.** [SQLI
32a60 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a  TE_MAX_LENGTH]..
32a70 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
32a80 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
32a90 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
32aa0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
32ab0 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
32ac0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
32ad0 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
32ae0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
32af0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
32b00 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
32b10 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
32b20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
32b30 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
32b40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
32b50 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
32b60 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
32b70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
32b80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32b90 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
32ba0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
32bb0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
32bc0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28  te3_bind_blob64(
32bd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
32be0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
32bf0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
32c00 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
32c10 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
32c20 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
32c30 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
32c40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
32c50 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
32c60 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
32c70 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
32c80 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
32c90 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
32ca0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
32cb0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
32cc0 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
32cd0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
32ce0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32cf0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
32d00 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
32d10 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73  3_stmt*,int,cons
32d20 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64  t char*,int,void
32d30 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
32d40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
32d50 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
32d60 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
32d70 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
32d80 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
32d90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
32da0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
32db0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
32dc0 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  ar*, sqlite3_uin
32dd0 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
32de0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
32df0 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
32e00 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
32e10 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ding);.int sqlit
32e20 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
32e30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32e40 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
32e50 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
32e60 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65  ite3_bind_pointe
32e70 72 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  r(sqlite3_stmt*,
32e80 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e   int, void*, con
32e90 73 74 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29  st char*,void(*)
32ea0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
32eb0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
32ec0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
32ed0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
32ee0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
32ef0 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69  _zeroblob64(sqli
32f00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
32f10 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
32f20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32f30 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
32f40 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45  Parameters.** ME
32f50 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
32f60 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  mt.**.** ^This r
32f70 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
32f80 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
32f90 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
32fa0 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
32fb0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
32fc0 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
32fd0 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
32fe0 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
32ff0 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
33000 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
33010 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
33020 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
33030 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
33040 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
33050 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
33060 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
33070 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
33080 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
33090 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
330a0 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
330b0 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
330c0 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
330d0 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
330e0 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
330f0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
33100 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
33110 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
33120 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
33130 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
33140 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
33150 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
33160 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
33170 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
33180 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
33190 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
331a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
331b0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
331c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
331d0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
331e0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
331f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
33200 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
33210 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
33220 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
33230 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
33240 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33250 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
33260 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54  Parameter.** MET
33270 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
33280 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
33290 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
332a0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
332b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
332c0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
332d0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
332e0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
332f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33300 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
33310 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
33320 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
33330 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
33340 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
33350 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
33360 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
33370 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
33380 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
33390 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
333a0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
333b0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
333c0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
333d0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
333e0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
333f0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
33400 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
33410 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
33420 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
33430 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
33440 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
33450 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
33460 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
33470 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
33480 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
33490 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
334a0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
334b0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
334c0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
334d0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
334e0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
334f0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
33500 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
33510 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
33520 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
33530 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
33540 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
33550 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
33560 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
33570 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
33580 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
33590 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
335a0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
335b0 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b  epare16()],.** [
335c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
335d0 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  6_v2()], or [sql
335e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
335f0 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  3()]..**.** See 
33600 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
33610 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
33620 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
33630 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
33640 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
33650 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
33660 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
33670 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
33680 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
33690 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
336a0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
336b0 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
336c0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
336d0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
336e0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
336f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
33700 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
33710 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
33720 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
33730 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
33740 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
33750 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
33760 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
33770 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
33780 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
33790 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
337a0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
337b0 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
337c0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
337d0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
337e0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
337f0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
33800 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
33810 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
33820 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
33830 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
33840 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
33850 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
33860 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
33870 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
33880 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
33890 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e  prepare16_v3()].
338a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
338b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
338c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
338d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
338e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
338f0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
33900 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
33910 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
33920 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33930 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
33940 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
33950 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
33960 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
33970 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
33980 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
33990 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
339a0 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
339b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
339c0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
339d0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
339e0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
339f0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
33a00 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
33a10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
33a20 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
33a30 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
33a40 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
33a50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
33a60 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
33a70 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
33a80 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
33a90 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
33aa0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
33ab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33ac0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
33ad0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
33ae0 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
33af0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
33b00 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
33b10 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
33b20 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
33b30 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
33b40 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
33b50 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20  statement]. ^If 
33b60 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
33b70 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61  urns 0, that mea
33b80 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  ns the .** [prep
33b90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33ba0 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20  returns no data 
33bb0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
33bc0 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48  [UPDATE])..** ^H
33bd0 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63  owever, just bec
33be0 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ause this routin
33bf0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69  e returns a posi
33c00 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73  tive number does
33c10 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61   not.** mean tha
33c20 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f  t one or more ro
33c30 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20  ws of data will 
33c40 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41  be returned.  ^A
33c50 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
33c60 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73  t.** will always
33c70 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76 65   have a positive
33c80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33c90 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70 65  count() but depe
33ca0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20  nding on the.** 
33cb0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
33cc0 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65  straints and the
33cd0 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20   table content, 
33ce0 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  it might return 
33cf0 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53  no rows..**.** S
33d00 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
33d10 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
33d20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
33d30 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
33d40 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
33d50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33d60 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
33d70 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
33d80 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
33d90 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
33da0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
33db0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
33dc0 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
33dd0 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
33de0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
33df0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
33e00 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
33e10 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
33e20 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
33e30 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
33e40 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
33e50 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
33e60 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
33e70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
33e80 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
33e90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
33ea0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
33eb0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
33ec0 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
33ed0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
33ee0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33ef0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
33f00 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
33f10 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
33f20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
33f30 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
33f40 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
33f50 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
33f60 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
33f70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
33f80 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
33f90 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
33fa0 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
33fb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33fc0 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
33fd0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
33fe0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
33ff0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
34000 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
34010 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
34020 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
34030 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
34040 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
34050 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
34060 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
34070 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
34080 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
34090 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
340a0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
340b0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
340c0 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
340d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
340e0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
340f0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
34100 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
34110 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
34120 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
34130 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
34140 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
34150 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
34160 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
34170 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
34180 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
34190 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
341a0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
341b0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
341c0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
341d0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
341e0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
341f0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
34200 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
34210 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
34220 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
34230 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
34240 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
34250 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
34260 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
34270 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
34280 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
34290 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
342a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
342b0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
342c0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
342d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
342e0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
342f0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
34300 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34310 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
34320 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
34330 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
34340 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
34350 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
34360 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
34370 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
34380 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
34390 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
343a0 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
343b0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
343c0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
343d0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
343e0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
343f0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
34400 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
34410 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
34420 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
34430 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
34440 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
34450 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
34460 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
34470 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
34480 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
34490 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
344a0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
344b0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
344c0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
344d0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
344e0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
344f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
34500 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
34510 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
34520 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
34530 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
34540 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
34550 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
34560 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
34570 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
34580 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
34590 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
345a0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
345b0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
345c0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
345d0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
345e0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
345f0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
34600 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
34610 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
34620 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
34630 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
34640 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
34650 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
34660 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
34670 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
34680 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34690 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
346a0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
346b0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
346c0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
346d0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
346e0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
346f0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
34700 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
34710 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
34720 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
34730 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
34740 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
34750 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
34760 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
34770 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
34780 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
34790 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
347a0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
347b0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
347c0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
347d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
347e0 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
347f0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
34800 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
34810 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
34820 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
34830 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
34840 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
34850 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
34860 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
34870 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
34880 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
34890 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
348a0 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
348b0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
348c0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
348d0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
348e0 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
348f0 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
34900 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
34910 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
34920 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
34930 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
34940 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
34950 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
34960 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
34970 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
34980 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
34990 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
349a0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
349b0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
349c0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
349d0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
349e0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
349f0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
34a00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
34a10 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
34a20 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
34a30 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
34a40 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
34a50 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
34a60 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
34a70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
34a80 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
34a90 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
34aa0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
34ab0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
34ac0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
34ad0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
34ae0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
34af0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34b00 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
34b10 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
34b20 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
34b30 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
34b40 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
34b50 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
34b60 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
34b70 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
34b80 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
34b90 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
34ba0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
34bb0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
34bc0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
34bd0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
34be0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
34bf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
34c00 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
34c10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
34c20 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
34c30 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
34c40 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
34c50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
34c60 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
34c70 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
34c80 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
34c90 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
34ca0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
34cb0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
34cc0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
34cd0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
34ce0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
34cf0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34d00 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
34d10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
34d20 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
34d30 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
34d40 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
34d50 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
34d60 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
34d70 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
34d80 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
34d90 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
34da0 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
34db0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
34dc0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
34dd0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
34de0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
34df0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
34e00 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
34e10 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
34e20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
34e30 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
34e40 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
34e50 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
34e60 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
34e70 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
34e80 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
34e90 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
34ea0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
34eb0 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
34ec0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
34ed0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
34ee0 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
34ef0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
34f00 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
34f10 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
34f20 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
34f30 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
34f40 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
34f50 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
34f60 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
34f70 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
34f80 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
34f90 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
34fa0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
34fb0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
34fc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
34fd0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
34fe0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
34ff0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
35000 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
35010 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
35020 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
35030 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
35040 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
35050 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
35060 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
35070 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
35080 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
35090 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
350a0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
350b0 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
350c0 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
350d0 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
350e0 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
350f0 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
35100 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
35110 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
35120 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
35130 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
35140 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
35150 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
35160 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
35170 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
35180 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
35190 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
351a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
351b0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
351c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
351d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
351e0 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
351f0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
35200 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
35210 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  _stmt.**.** Afte
35220 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
35230 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
35240 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
35250 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69   any of.** [sqli
35260 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
35270 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
35280 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69  are_v3()], [sqli
35290 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
352a0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
352b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
352c0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
352d0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
352e0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
352f0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
35300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
35310 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
35320 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
35330 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
35340 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
35350 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
35360 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
35370 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
35380 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
35390 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
353a0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
353b0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
353c0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
353d0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
353e0 77 65 72 20 22 76 58 22 20 69 6e 74 65 72 66 61  wer "vX" interfa
353f0 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ces.** [sqlite3_
35400 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b  prepare_v3()], [
35410 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
35420 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
35430 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c  prepare16_v3()],
35440 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
35450 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
35460 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
35470 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
35480 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
35490 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
354a0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
354b0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
354c0 20 6e 65 77 20 22 76 58 22 20 69 6e 74 65 72 66   new "vX" interf
354d0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
354e0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
354f0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
35500 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
35510 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
35520 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
35530 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
35540 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
35550 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
35560 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
35570 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
35580 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
35590 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
355a0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
355b0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
355c0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
355d0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
355e0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
355f0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
35600 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
35610 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
35620 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
35630 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
35640 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
35650 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
35660 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
35670 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
35680 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
35690 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
356a0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
356b0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
356c0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
356d0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
356e0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
356f0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
35700 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
35710 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
35720 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
35730 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
35740 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
35750 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
35760 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
35770 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
35780 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
35790 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
357a0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
357b0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
357c0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
357d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
357e0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
357f0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
35800 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
35810 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
35820 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
35830 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
35840 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
35850 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
35860 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
35870 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
35880 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
35890 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
358a0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
358b0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
358c0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
358d0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
358e0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
358f0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
35900 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
35910 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
35920 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
35930 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
35940 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
35950 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
35960 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
35970 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
35980 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
35990 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
359a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
359b0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
359c0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
359d0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
359e0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
359f0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
35a00 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
35a10 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
35a20 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
35a30 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
35a40 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
35a50 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
35a60 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
35a70 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
35a80 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
35a90 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
35aa0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
35ab0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
35ac0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
35ad0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
35ae0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
35af0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
35b00 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
35b10 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
35b20 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
35b30 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
35b40 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
35b50 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
35b60 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
35b70 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
35b80 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
35b90 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
35ba0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
35bb0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
35bc0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
35bd0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
35be0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
35bf0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
35c00 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
35c10 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
35c20 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
35c30 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
35c40 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
35c50 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
35c60 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
35c70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
35c80 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
35c90 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
35ca0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
35cb0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
35cc0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
35cd0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
35ce0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
35cf0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
35d00 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
35d10 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
35d20 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
35d30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
35d40 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
35d50 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
35d60 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
35d70 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
35d80 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
35d90 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
35da0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
35db0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
35dc0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
35dd0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
35de0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
35df0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
35e00 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
35e10 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
35e20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
35e30 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
35e40 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
35e50 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
35e60 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
35e70 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
35e80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
35e90 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
35ea0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
35eb0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
35ec0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
35ed0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
35ee0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
35ef0 75 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f  ut after [versio
35f00 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61  n 3.6.23.1] ([da
35f10 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a  teof:3.6.23.1],.
35f20 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
35f30 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
35f40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
35f50 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
35f60 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
35f70 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
35f80 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
35f90 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
35fa0 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
35fb0 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
35fc0 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
35fd0 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
35fe0 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
35ff0 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
36000 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
36010 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
36020 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
36030 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
36040 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
36050 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
36060 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
36070 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
36080 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
36090 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
360a0 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
360b0 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
360c0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
360d0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
360e0 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
360f0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
36100 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
36110 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
36120 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
36130 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
36140 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
36150 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
36160 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
36170 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
36180 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
36190 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
361a0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
361b0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
361c0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
361d0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
361e0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
361f0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
36200 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
36210 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
36220 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
36230 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
36240 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
36250 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
36260 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
36270 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
36280 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
36290 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
362a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
362b0 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72  pare_v2()].** or
362c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
362d0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  e16_v2()] or [sq
362e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
362f0 76 33 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v3()] instead.**
36300 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
36310 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
36320 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36330 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
36340 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
36350 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
36360 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
36370 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
36380 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
36390 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
363a0 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 58  e use of the "vX
363b0 22 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  " interfaces is 
363c0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
363d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
363e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
363f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36400 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
36410 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
36420 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
36430 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
36440 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
36450 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
36460 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
36470 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
36480 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
36490 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
364a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
364b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
364c0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
364d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
364e0 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
364f0 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
36500 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
36510 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
36520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
36530 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
36540 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
36550 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
36560 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
36570 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
36580 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36590 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
365a0 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
365b0 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
365c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
365d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
365e0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
365f0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
36600 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
36610 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
36620 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
36630 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
36640 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
36650 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
36660 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
36670 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
36680 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
36690 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
366a0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
366b0 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
366c0 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
366d0 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
366e0 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
366f0 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
36700 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
36710 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
36720 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
36730 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
36740 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
36750 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
36760 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
36770 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
36780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
36790 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
367a0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
367b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
367c0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
367d0 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
367e0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
367f0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
36800 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
36810 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
36820 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
36830 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
36840 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
36850 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
36860 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
36870 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
36880 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
36890 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
368a0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
368b0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
368c0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
368d0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
368e0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
368f0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
36900 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
36910 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
36920 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
36930 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
36940 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
36950 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
36960 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
36970 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
36980 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
36990 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
369a0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
369b0 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
369c0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
369d0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
369e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
369f0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
36a00 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
36a10 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
36a20 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
36a30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
36a40 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
36a50 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
36a60 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
36a70 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
36a80 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
36a90 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
36aa0 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
36ab0 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
36ac0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
36ad0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
36ae0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
36af0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
36b00 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
36b10 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
36b20 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f  ** <b>Summary:</
36b30 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  b>.** <blockquot
36b40 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  e><table border=
36b50 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20  0 cellpadding=0 
36b60 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a  cellspacing=0>.*
36b70 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
36b80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36b90 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
36ba0 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a  d>BLOB result.**
36bb0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
36bc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
36bd0 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
36be0 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a  td>REAL result.*
36bf0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
36c00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c  ite3_column_int<
36c10 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
36c20 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20  >32-bit INTEGER 
36c30 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
36c40 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
36c50 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64  umn_int64</b><td
36c60 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69  >&rarr;<td>64-bi
36c70 74 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74  t INTEGER result
36c80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
36c90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36ca0 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  xt</b><td>&rarr;
36cb0 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54 20 72  <td>UTF-8 TEXT r
36cc0 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
36cd0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
36ce0 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64  mn_text16</b><td
36cf0 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31  >&rarr;<td>UTF-1
36d00 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a  6 TEXT result.**
36d10 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
36d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
36d30 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
36d40 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61 73 20  d>The result as 
36d50 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  an .** [sqlite3_
36d60 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74 65  value|unprotecte
36d70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36d80 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e   object..** <tr>
36d90 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e  <td>&nbsp;<td>&n
36da0 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a  bsp;<td>&nbsp;.*
36db0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
36dc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36dd0 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  s</b><td>&rarr;<
36de0 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f  td>Size of a BLO
36df0 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38 20  B.** or a UTF-8 
36e00 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e 20 62  TEXT result in b
36e10 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ytes.** <tr><td>
36e20 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
36e30 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70 3b 26  n_bytes16&nbsp;&
36e40 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64  nbsp;</b>.** <td
36e50 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62  >&rarr;&nbsp;&nb
36e60 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55  sp;<td>Size of U
36e70 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e  TF-16.** TEXT in
36e80 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74   bytes.** <tr><t
36e90 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
36ea0 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e  umn_type</b><td>
36eb0 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c  &rarr;<td>Defaul
36ec0 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20 6f 66  t.** datatype of
36ed0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c   the result.** <
36ee0 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75  /table></blockqu
36ef0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65  ote>.**.** <b>De
36f00 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  tails:</b>.**.**
36f10 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
36f20 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
36f30 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
36f40 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
36f50 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
36f60 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
36f70 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
36f80 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
36f90 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
36fa0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
36fb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36fc0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
36fd0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
36fe0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
36ff0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
37000 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
37010 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
37020 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
37030 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
37040 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
37050 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
37060 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
37070 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
37080 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
37090 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
370a0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
370b0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
370c0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
370d0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
370e0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
370f0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
37100 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
37110 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
37120 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
37130 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
37140 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
37150 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
37160 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
37170 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
37180 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
37190 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
371a0 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
371b0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
371c0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
371d0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
371e0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
371f0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
37200 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
37210 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
37220 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
37230 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
37240 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
37250 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
37260 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
37270 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
37280 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
37290 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
372a0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
372b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
372c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
372d0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
372e0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
372f0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
37300 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
37310 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
37320 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
37330 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
37340 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
37350 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
37360 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
37370 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
37380 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
37390 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
373a0 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
373b0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
373c0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
373d0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
373e0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
373f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
37400 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74  he first six int
37410 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20  erfaces (_blob, 
37420 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f  _double, _int, _
37430 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e  int64, _text, an
37440 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65 61  d _text16).** ea
37450 63 68 20 72 65 74 75 72 6e 20 74 68 65 20 76 61  ch return the va
37460 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  lue of a result 
37470 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65 63  column in a spec
37480 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d 61 74  ific data format
37490 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73  .  If.** the res
374a0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f  ult column is no
374b0 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74  t initially in t
374c0 68 65 20 72 65 71 75 65 73 74 65 64 20 66 6f 72  he requested for
374d0 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  mat (for example
374e0 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75 65 72  ,.** if the quer
374f0 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  y returns an int
37500 65 67 65 72 20 62 75 74 20 74 68 65 20 73 71 6c  eger but the sql
37510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
37520 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
37530 69 73 20 75 73 65 64 20 74 6f 20 65 78 74 72 61  is used to extra
37540 63 74 20 74 68 65 20 76 61 6c 75 65 29 20 74 68  ct the value) th
37550 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  en an automatic 
37560 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
37570 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a  is performed..**
37580 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37590 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
375a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
375b0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
375c0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
375d0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
375e0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
375f0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
37600 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
37610 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
37620 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
37630 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
37640 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
37650 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
37660 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
37670 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a  SQLITE_NULL]..**
37680 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
37690 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  e of sqlite3_col
376a0 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e 20 62  umn_type() can b
376b0 65 20 75 73 65 64 20 74 6f 20 64 65 63 69 64 65  e used to decide
376c0 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65   which.** of the
376d0 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72   first six inter
376e0 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65 20 75  face should be u
376f0 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74  sed to extract t
37700 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e  he column value.
37710 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65  .** The value re
37720 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
37730 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
37740 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
37750 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f  ul if no.** auto
37760 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65  matic type conve
37770 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
37780 72 72 65 64 20 66 6f 72 20 74 68 65 20 76 61 6c  rred for the val
37790 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20  ue in question. 
377a0 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74 79 70   .** After a typ
377b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68  e conversion, th
377c0 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c  e result of call
377d0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ing sqlite3_colu
377e0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73 20  mn_type().** is 
377f0 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f 75 67  undefined, thoug
37800 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46 75 74  h harmless.  Fut
37810 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
37820 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
37830 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
37840 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
37850 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
37860 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
37870 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
37880 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
37890 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20 54 45  s a BLOB or a TE
378a0 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  XT string, then 
378b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
378c0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72  mn_bytes().** or
378d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
378e0 62 79 74 65 73 31 36 28 29 20 69 6e 74 65 72 66  bytes16() interf
378f0 61 63 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  aces can be used
37900 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
37910 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61  e size.** of tha
37920 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
37930 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
37940 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
37950 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
37960 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
37970 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
37980 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
37990 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
379a0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
379b0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
379c0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
379d0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
379e0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
379f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
37a00 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
37a10 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
37a20 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
37a30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
37a40 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
37a50 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
37a60 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
37a70 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
37a80 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
37a90 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
37aa0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
37ab0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
37ac0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
37ad0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
37ae0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
37af0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
37b00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
37b10 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
37b20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37b30 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
37b40 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
37b50 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
37b60 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
37b70 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
37b80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
37b90 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
37ba0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
37bb0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
37bc0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
37bd0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
37be0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
37bf0 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
37c00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37c10 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
37c20 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
37c30 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
37c40 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
37c50 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
37c60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
37c70 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
37c80 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
37c90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
37ca0 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
37cb0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
37cc0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
37cd0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
37ce0 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
37cf0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
37d00 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
37d10 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
37d20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
37d30 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
37d40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37d50 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
37d60 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
37d70 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
37d80 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
37d90 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
37da0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
37db0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
37dc0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
37dd0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
37de0 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
37df0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
37e00 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
37e10 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
37e20 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
37e30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
37e40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
37e50 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
37e60 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
37e70 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
37e80 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
37e90 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
37ea0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
37eb0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
37ec0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
37ed0 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
37ee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
37ef0 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
37f00 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
37f10 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
37f20 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
37f30 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
37f40 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
37f50 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
37f60 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
37f70 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
37f80 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72  er..**.** <b>War
37f90 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f  ning:</b> ^The o
37fa0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
37fb0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
37fc0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
37fd0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
37fe0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
37ff0 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75  object.  In a mu
38000 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69  ltithreaded envi
38010 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75  ronment,.** an u
38020 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
38030 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
38040 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
38050 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20   safely with.** 
38060 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
38070 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
38080 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
38090 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
380a0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
380b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
380c0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
380d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
380e0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
380f0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
38100 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
38110 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
38120 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
38130 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
38140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
38150 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
38160 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
38170 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69  s()], the behavi
38180 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  or is not thread
38190 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  safe..** Hence, 
381a0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
381b0 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  mn_value() inter
381c0 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61  face.** is norma
381d0 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20  lly only useful 
381e0 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70 6c 65  within the imple
381f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a  mentation of .**
38200 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
38210 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
38220 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c  ons] or [virtual
38230 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69   tables], not wi
38240 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  thin.** top-leve
38250 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  l application co
38260 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  de..**.** The th
38270 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
38280 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
38290 65 72 74 20 74 68 65 20 64 61 74 61 74 79 70 65  ert the datatype
382a0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a   of the result..
382b0 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c  ** ^For example,
382c0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
382d0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
382e0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
382f0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
38300 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
38310 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
38320 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
38330 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
38340 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
38350 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
38360 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
38370 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
38380 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
38390 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
383a0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
383b0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
383c0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
383d0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
383e0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
383f0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
38400 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
38410 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
38420 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
38430 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
38440 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
38450 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
38460 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
38470 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
38480 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
38490 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
384a0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
384b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
384c0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
384d0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
384e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
384f0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
38500 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
38510 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
38520 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
38530 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
38540 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
38550 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
38560 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
38570 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
38580 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
38590 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
385a0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
385b0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
385c0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
385d0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
385e0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
385f0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
38600 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
38610 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
38620 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
38630 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
38640 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
38650 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
38660 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
38670 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
38680 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
38690 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
386a0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
386b0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
386c0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
386d0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
386e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
386f0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
38700 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
38710 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
38720 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
38730 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
38740 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 4