/ Hex Artifact Content
Login

Artifact bd7a60793790a9ea7be03c5402bf2fe8c6a1156f5ab43cdec9a7e01fcb1ac402:


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 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
6940: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6950: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
6960: 30 30 30 30 20 2a 2f 0a 23 64 65 66 69 6e 65 20  0000 */.#define 
6970: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
6980: 45 44 5f 53 43 48 45 4d 41 20 20 20 20 30 78 30  ED_SCHEMA    0x0
6990: 31 30 30 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  1000000  /* Ok f
69a0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
69b0: 76 32 28 29 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  v2() */.../*.** 
69c0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
69d0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
69e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
69f0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6a00: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
6a10: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6a20: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
6a30: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
6a40: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
6a50: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
6a60: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
6a70: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
6a80: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
6a90: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
6aa0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
6ab0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
6ac0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6ad0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
6ae0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6b10: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6b20: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6b30: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6b40: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6b50: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
6b60: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6b70: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6b80: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
6b90: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
6ba0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
6bb0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6bc0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6bd0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6be0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6bf0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6c00: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6c10: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6c20: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6c30: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6c40: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6c50: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
6c60: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6c70: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6c80: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
6c90: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
6ca0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
6cb0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6cc0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6cd0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6ce0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6cf0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6d00: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6d10: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6d20: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6d30: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6d40: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
6d50: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6d60: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
6d70: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
6d80: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
6d90: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
6da0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
6db0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
6dc0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
6dd0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
6de0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6df0: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6e00: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6e10: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6e20: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6e30: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
6e40: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
6e50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6e60: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6e70: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63  EN.** flag indic
6e80: 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65  ates that a file
6e90: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6ea0: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6eb0: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
6ec0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
6ed0: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
6ee0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
6ef0: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
6f00: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
6f10: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6f20: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
6f30: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
6f40: 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ileges..**.** Th
6f50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42  e SQLITE_IOCAP_B
6f60: 41 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70  ATCH_ATOMIC prop
6f70: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
6f80: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a  the underlying.*
6f90: 2a 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70  * filesystem sup
6fa0: 70 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74  ports doing mult
6fb0: 69 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61  iple write opera
6fc0: 74 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79  tions atomically
6fd0: 20 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77   when those.** w
6fe0: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
6ff0: 61 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79  are bracketed by
7000: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
7010: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
7020: 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54  E] and.** [SQLIT
7030: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
7040: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f  TOMIC_WRITE]..*/
7050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7060: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
7070: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7080: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
7090: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
70a0: 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20  MIC512          
70b0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
70c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
70d0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
70e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
70f0: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
7100: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7110: 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C2K             
7120: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
7130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7140: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
7150: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
7160: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
7170: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
7180: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
7190: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
71a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
71b0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
71c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
71d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
71e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
71f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7200: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65  00000080.#define
7210: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7220: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20  OMIC64K         
7230: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
7240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7250: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7260: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7270: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
7280: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7290: 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20  ENTIAL          
72a0: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64     0x00000400.#d
72b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
72c0: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
72d0: 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30  HEN_OPEN  0x0000
72e0: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
72f0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
7300: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
7310: 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66   0x00001000.#def
7320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7330: 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20  _IMMUTABLE      
7340: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30          0x000020
7350: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7360: 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54  E_IOCAP_BATCH_AT
7370: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30  OMIC           0
7380: 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00004000../*.**
7390: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
73a0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
73b0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
73c0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
73d0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
73e0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
73f0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
7400: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
7410: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7420: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
7430: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
7440: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
7450: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
7460: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
7470: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
7480: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
7490: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
74a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
74b0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
74c0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
74d0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
74e0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
74f0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
7500: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
7510: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
7520: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
7530: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
7540: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
7550: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
7560: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
7570: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7580: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
7590: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
75a0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
75b0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
75c0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
75d0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
75e0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
75f0: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
7600: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
7610: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
7620: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
7630: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
7640: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
7650: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
7660: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
7670: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
7680: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
7690: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
76a0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
76b0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
76c0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
76d0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
76e0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
76f0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7700: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
7710: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
7720: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
7730: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
7740: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
7750: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
7760: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
7770: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
7780: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7790: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
77a0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
77b0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
77c0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
77d0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
77e0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
77f0: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
7800: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
7810: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
7820: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
7830: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
7840: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
7850: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
7860: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
7870: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
7880: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
7890: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
78a0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
78b0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
78c0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
78d0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
78e0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
78f0: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7900: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7910: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7920: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7930: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7940: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
7950: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
7960: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
7970: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
7980: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
7990: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
79a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
79b0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
79c0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
79d0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
79e0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
79f0: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7a00: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7a10: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7a20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7a30: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7a40: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
7a50: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7a60: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
7a70: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
7a80: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7a90: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
7aa0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7ab0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
7ac0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
7ad0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7ae0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7af0: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7b00: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7b10: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7b20: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7b30: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7b40: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
7b50: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7b60: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
7b70: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
7b80: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
7b90: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
7ba0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
7bb0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
7bc0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
7bd0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7be0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7bf0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7c00: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7c10: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7c20: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7c30: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7c40: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
7c50: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7c60: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
7c70: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
7c80: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
7c90: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
7ca0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
7cb0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
7cc0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
7cd0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7ce0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7cf0: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7d00: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7d10: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7d20: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7d30: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7d40: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7d50: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
7d60: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7d70: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
7d80: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
7d90: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
7da0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7db0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
7dc0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
7dd0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7de0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7df0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7e00: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7e10: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7e20: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7e30: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7e40: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
7e50: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
7e60: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
7e70: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
7e80: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
7e90: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
7ea0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7eb0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
7ec0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
7ed0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7ee0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7ef0: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7f00: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7f10: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7f20: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7f30: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7f40: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
7f50: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
7f60: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
7f70: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
7f80: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
7f90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
7fa0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
7fb0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7fc0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
7fd0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7fe0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7ff0: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
8000: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
8010: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
8020: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
8030: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
8040: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
8050: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
8060: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
8070: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
8080: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
8090: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
80a0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
80b0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
80c0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
80d0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
80e0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
80f0: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
8100: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
8110: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
8120: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
8130: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
8140: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
8150: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
8160: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
8170: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
8180: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
8190: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
81a0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
81b0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
81c0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
81d0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
81e0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
81f0: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
8200: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
8210: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
8220: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
8230: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
8240: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
8250: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
8260: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
8270: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
8280: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
8290: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
82a0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
82b0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
82c0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
82d0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
82e0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
82f0: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
8300: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
8310: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
8320: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
8330: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
8340: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
8350: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
8360: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
8370: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
8380: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
8390: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
83a0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
83b0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
83c0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
83d0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
83e0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
83f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8400: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
8410: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
8420: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
8430: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
8440: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
8450: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
8460: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
8470: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
8480: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
8490: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
84a0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
84b0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
84c0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
84d0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
84e0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
84f0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
8500: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
8510: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
8520: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
8530: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
8540: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
8550: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
8560: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
8570: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
8580: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
8590: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
85a0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
85b0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
85c0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
85d0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
85e0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
85f0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
8600: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
8610: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
8620: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
8630: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
8640: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
8650: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
8660: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
8670: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
8680: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8690: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
86a0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
86b0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
86c0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
86d0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
86e0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
86f0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
8700: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
8710: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
8720: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
8730: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
8740: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
8750: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
8760: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
8770: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
8780: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
8790: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
87a0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
87b0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
87c0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
87d0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
87e0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
87f0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
8800: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
8810: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
8820: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
8830: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
8840: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
8850: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
8860: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
8870: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
8880: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
8890: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
88a0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
88b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88c0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
88d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
88e0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
88f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8900: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8910: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8920: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8930: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8940: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8950: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8960: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8970: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8980: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
8990: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
89a0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
89b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
89c0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
89d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
89e0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
89f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8a00: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
8a10: 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69  HEN_OPEN].** <li
8a20: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8a30: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
8a40: 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ITE].** <li> [SQ
8a50: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
8a60: 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ABLE].** <li> [S
8a70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43  QLITE_IOCAP_BATC
8a80: 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75  H_ATOMIC].** </u
8a90: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
8aa0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8ab0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8ac0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
8ad0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
8ae0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8af0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8b00: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
8b10: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
8b20: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
8b30: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
8b40: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
8b50: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
8b60: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
8b70: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
8b80: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
8b90: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8ba0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8bb0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
8bc0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
8bd0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
8be0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
8bf0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
8c00: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
8c10: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
8c20: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
8c30: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
8c40: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
8c50: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8c60: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
8c70: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8c80: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
8c90: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
8ca0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
8cb0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
8cc0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
8cd0: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
8ce0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
8cf0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
8d00: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
8d10: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
8d20: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
8d30: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
8d40: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
8d50: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
8d60: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8d70: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
8d80: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
8d90: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
8da0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8db0: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
8dc0: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
8dd0: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
8de0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
8df0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8e00: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
8e10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
8e20: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8e30: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
8e40: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
8e50: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
8e60: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8e70: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
8e80: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
8e90: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8ea0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8eb0: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8ec0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ed0: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
8ee0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8ef0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8f00: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
8f10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8f20: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
8f30: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
8f40: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
8f50: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8f60: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
8f70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8f80: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8f90: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8fa0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8fb0: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8fc0: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8fd0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8fe0: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
8ff0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
9000: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
9010: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
9020: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
9030: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
9040: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
9050: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
9060: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
9070: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
9080: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
9090: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
90a0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
90b0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
90c0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
90d0: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
90e0: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
90f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
9100: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
9110: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
9120: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
9130: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
9140: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
9150: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
9160: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
9170: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
9180: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
9190: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
91a0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
91b0: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
91c0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
91d0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
91e0: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
91f0: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
9200: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
9210: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
9220: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
9230: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
9240: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
9250: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
9260: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
9270: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
9280: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
9290: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
92a0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
92b0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
92c0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
92d0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
92e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
92f0: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
9300: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
9310: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65   KEYWORDS: {file
9320: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
9330: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  } {file control 
9340: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  opcode}.**.** Th
9350: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
9360: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
9370: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
9380: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
9390: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
93a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
93b0: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
93c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
93d0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
93e0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rface..**.** <ul
93f0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
9400: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
9410: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
9420: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
9430: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
9440: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
9450: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
9460: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
9470: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
9480: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
9490: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
94a0: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
94b0: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
94c0: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
94d0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
94e0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
94f0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
9500: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
9510: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
9520: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
9530: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
9540: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
9550: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
9560: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
9570: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
9580: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73  g testing and is
9590: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
95a0: 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  when the SQLITE_
95b0: 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  TEST.** compile-
95c0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75  time option is u
95d0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  sed..**.** <li>[
95e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
95f0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
9600: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
9610: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
9620: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
9630: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
9640: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
9650: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
9660: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9670: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
9680: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
9690: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
96a0: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
96b0: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
96c0: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
96d0: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
96e0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
96f0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
9700: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
9710: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
9720: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
9730: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
9740: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
9750: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
9760: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
9770: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
9780: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9790: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c  ITE_FCNTL_SIZE_L
97a0: 49 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  IMIT]].** The [S
97b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
97c0: 5f 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65 20 69  _LIMIT] opcode i
97d0: 73 20 75 73 65 64 20 62 79 20 69 6e 2d 6d 65 6d  s used by in-mem
97e0: 6f 72 79 20 56 46 53 20 74 68 61 74 0a 2a 2a 20  ory VFS that.** 
97f0: 69 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71 6c 69  implements [sqli
9800: 74 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28  te3_deserialize(
9810: 29 5d 20 74 6f 20 73 65 74 20 61 6e 20 75 70 70  )] to set an upp
9820: 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20  er bound on the 
9830: 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69  size.** of the i
9840: 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
9850: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
9860: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9870: 20 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36   a [sqlite3_int6
9880: 34 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e  4]..** If the in
9890: 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f  teger pointed to
98a0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
98b0: 65 6e 20 69 74 20 69 73 20 66 69 6c 6c 65 64 20  en it is filled 
98c0: 69 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 63  in with the.** c
98d0: 75 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20 20 4f  urrent limit.  O
98e0: 74 68 65 72 77 69 73 65 20 74 68 65 20 6c 69 6d  therwise the lim
98f0: 69 74 20 69 73 20 73 65 74 20 74 6f 20 74 68 65  it is set to the
9900: 20 6c 61 72 67 65 72 20 6f 66 20 74 68 65 20 76   larger of the v
9910: 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69  alue.** of the i
9920: 6e 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74  nteger pointed t
9930: 6f 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e  o and the curren
9940: 74 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 2e  t database size.
9950: 20 20 54 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a    The integer.**
9960: 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 73   pointed to is s
9970: 65 74 20 74 6f 20 74 68 65 20 6e 65 77 20 6c 69  et to the new li
9980: 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  mit..**.** <li>[
9990: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
99a0: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
99b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
99c0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
99d0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
99e0: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
99f0: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
9a00: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
9a10: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
9a20: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
9a30: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
9a40: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
9a50: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
9a60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
9a70: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
9a80: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
9a90: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
9aa0: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
9ab0: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
9ac0: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
9ad0: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
9ae0: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
9af0: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
9b00: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
9b10: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
9b20: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
9b30: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
9b40: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
9b50: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
9b60: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
9b70: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
9b80: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9b90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9ba0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
9bb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
9bc0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
9bd0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
9be0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
9bf0: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
9c00: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9c10: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9c20: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9c30: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9c40: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
9c50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
9c60: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  RNAL_POINTER]..*
9c70: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9c80: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9c90: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
9ca0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
9cb0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20  OURNAL_POINTER] 
9cc0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9cd0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9ce0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9cf0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9d00: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9d10: 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66  th the journal f
9d20: 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74  ile (either.** t
9d30: 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75  he [rollback jou
9d40: 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72  rnal] or the [wr
9d50: 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20  ite-ahead log]) 
9d60: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
9d70: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9d80: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c  nection.  See al
9d90: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  so [SQLITE_FCNTL
9da0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a  _FILE_POINTER]..
9db0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9dc0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
9dd0: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
9de0: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9df0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9e00: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
9e10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9e20: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
9e30: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9e40: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9e50: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
9e60: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
9e70: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
9e80: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
9e90: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
9ea0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
9eb0: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
9ec0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9ed0: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
9ee0: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9ef0: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9f00: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
9f10: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
9f20: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
9f30: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
9f40: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
9f50: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
9f60: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9f70: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
9f80: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
9f90: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
9fa0: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
9fb0: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
9fc0: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
9fd0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
9fe0: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9ff0: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
a000: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
a010: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
a020: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
a030: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
a040: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
a050: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
a060: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
a070: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
a080: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
a090: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
a0a0: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
a0b0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
a0c0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
a0d0: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
a0e0: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
a0f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a100: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
a110: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
a120: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
a130: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
a140: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
a150: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
a160: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
a170: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a180: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
a190: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
a1a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
a1b0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
a1c0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
a1d0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
a1e0: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
a1f0: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
a200: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
a210: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
a220: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
a230: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
a240: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
a250: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
a260: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
a270: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
a280: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
a290: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
a2a0: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
a2b0: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
a2c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a2d0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
a2e0: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
a2f0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
a300: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
a310: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
a320: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
a330: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
a340: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
a350: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
a360: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
a370: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a380: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
a390: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
a3a0: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
a3b0: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
a3c0: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
a3d0: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
a3e0: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
a3f0: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
a400: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
a410: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
a420: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
a430: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
a440: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
a450: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
a460: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
a470: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
a480: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
a490: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
a4a0: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
a4b0: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
a4c0: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
a4d0: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
a4e0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
a4f0: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
a500: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
a510: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
a520: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
a530: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
a540: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
a550: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
a560: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
a570: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
a580: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
a590: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
a5a0: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
a5b0: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
a5c0: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
a5d0: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
a5e0: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
a5f0: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
a600: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
a610: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
a620: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
a630: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
a640: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
a650: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
a660: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
a670: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
a680: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
a690: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
a6a0: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
a6b0: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
a6c0: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
a6d0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
a6e0: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
a6f0: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
a700: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
a710: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
a720: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
a730: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
a740: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
a750: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
a760: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
a770: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
a780: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
a790: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
a7a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a7b0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
a7c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a7d0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
a7e0: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
a7f0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
a800: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
a810: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
a820: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
a830: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
a840: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
a850: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
a860: 6f 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20  og ([WAL file]) 
a870: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
a880: 79 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65 64 20  y.** files used 
a890: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
a8a0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
a8b0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
a8c0: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
a8d0: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
a8e0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
a8f0: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
a900: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
a910: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
a920: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
a930: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
a940: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
a950: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
a960: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
a970: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
a980: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
a990: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
a9a0: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
a9b0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
a9c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
a9d0: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
a9e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
a9f0: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
aa00: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
aa10: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
aa20: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
aa30: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
aa40: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
aa50: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
aa60: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
aa70: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
aa80: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
aa90: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
aaa0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
aab0: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
aac0: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
aad0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
aae0: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
aaf0: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
ab00: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
ab10: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
ab20: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
ab30: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
ab40: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
ab50: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
ab60: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
ab70: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ab80: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
ab90: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
aba0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
abb0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
abc0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
abd0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
abe0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
abf0: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
ac00: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
ac10: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
ac20: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
ac30: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
ac40: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
ac50: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
ac60: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
ac70: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
ac80: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
ac90: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
aca0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
acb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
acc0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
acd0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
ace0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
acf0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
ad00: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
ad10: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
ad20: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
ad30: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
ad40: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
ad50: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
ad60: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
ad70: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
ad80: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
ad90: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
ada0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
adb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
adc0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
add0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
ade0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
adf0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
ae00: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
ae10: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
ae20: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
ae30: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
ae40: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
ae50: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
ae60: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
ae70: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
ae80: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
ae90: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
aea0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
aeb0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
aec0: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
aed0: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
aee0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
aef0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
af00: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
af10: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
af20: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
af30: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
af40: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
af50: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
af60: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
af70: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
af80: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
af90: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
afa0: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
afb0: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
afc0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
afd0: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
afe0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
aff0: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
b000: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
b010: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
b020: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
b030: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
b040: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
b050: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
b060: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
b070: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
b080: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
b090: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
b0a0: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
b0b0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
b0c0: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
b0d0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
b0e0: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
b0f0: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
b100: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
b110: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
b120: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
b130: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
b140: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
b150: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
b160: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
b170: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
b180: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
b190: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
b1a0: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
b1b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b1c0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
b1d0: 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TER]].** ^The [S
b1e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
b1f0: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
b200: 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20  finds a pointer 
b210: 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c  to the top-level
b220: 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72  .** [VFSes] curr
b230: 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e  ently in use.  ^
b240: 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20  (The argument X 
b250: 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  in.** sqlite3_fi
b260: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51  le_control(db,SQ
b270: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
b280: 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62  OINTER,X) must b
b290: 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73  e.** of type "[s
b2a0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e  qlite3_vfs] **".
b2b0: 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77    This opcodes w
b2c0: 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f  ill set *X.** to
b2d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
b2e0: 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e  e top-level VFS.
b2f0: 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72  )^.** ^When ther
b300: 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56  e are multiple V
b310: 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20  FS shims in the 
b320: 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f  stack, this opco
b330: 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20  de finds the.** 
b340: 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20  upper-most shim 
b350: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
b360: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
b370: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
b380: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
b390: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
b3a0: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
b3b0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
b3c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
b3d0: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
b3e0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
b3f0: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
b400: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
b410: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
b420: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
b430: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
b440: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
b450: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
b460: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b470: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
b480: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
b490: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
b4a0: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
b4b0: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
b4c0: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
b4d0: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
b4e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
b4f0: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
b500: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
b510: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
b520: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
b530: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
b540: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
b550: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
b560: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
b570: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b580: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
b590: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
b5a0: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
b5b0: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
b5c0: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
b5d0: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
b5e0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
b5f0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
b600: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
b610: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
b620: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
b630: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
b640: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
b650: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
b660: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
b670: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
b680: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
b690: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
b6a0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
b6b0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
b6c0: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
b6d0: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
b6e0: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
b6f0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
b700: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b710: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b720: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
b730: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
b740: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
b750: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
b760: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
b770: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
b780: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
b790: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
b7a0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
b7b0: 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69  t if result stri
b7c0: 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74  ng is NULL, or t
b7d0: 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f  hat returns a co
b7e0: 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  py.** of the res
b7f0: 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68  ult string if th
b800: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d  e string is non-
b810: 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  NULL..** ^If the
b820: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b830: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b840: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  rol returns.** a
b850: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f  ny result code o
b860: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
b870: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45  E_OK] or [SQLITE
b880: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74  _NOTFOUND], that
b890: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74   means.** that t
b8a0: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72  he VFS encounter
b8b0: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c  ed an error whil
b8c0: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b  e handling the [
b8d0: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a  PRAGMA] and the.
b8e0: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f  ** compilation o
b8f0: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69  f the PRAGMA fai
b900: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ls with an error
b910: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
b920: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
b930: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63   file control oc
b940: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69  curs at the begi
b950: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20  nning of pragma 
b960: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73  statement analys
b970: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20  is and so.** it 
b980: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72  is able to overr
b990: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52  ide built-in [PR
b9a0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
b9b0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b9c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b9d0: 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  ANDLER]].** ^The
b9e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
b9f0: 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66  USYHANDLER].** f
ba00: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20  ile-control may 
ba10: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  be invoked by SQ
ba20: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61  Lite on the data
ba30: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  base file handle
ba40: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65  .** shortly afte
ba50: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69  r it is opened i
ba60: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
ba70: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20  de a custom VFS 
ba80: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74  with access.** t
ba90: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  o the connection
baa0: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63  s busy-handler c
bab0: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67  allback. The arg
bac0: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65  ument is of type
bad0: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20   (void **).** - 
bae0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20  an array of two 
baf0: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e  (void *) values.
bb00: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64   The first (void
bb10: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69   *) actually poi
bb20: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63  nts.** to a func
bb30: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e  tion of type (in
bb40: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20  t (*)(void *)). 
bb50: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f  In order to invo
bb60: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ke the connectio
bb70: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c  ns.** busy-handl
bb80: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  er, this functio
bb90: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f  n should be invo
bba0: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63  ked with the sec
bbb0: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a  ond (void *) in.
bbc0: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20  ** the array as 
bbd0: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  the only argumen
bbe0: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  t. If it returns
bbf0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
bc00: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
bc10: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69   should be retri
bc20: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  ed. If it return
bc30: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74  s zero, the cust
bc40: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62  om VFS should ab
bc50: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72  andon the.** cur
bc60: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a  rent operation..
bc70: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bc80: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
bc90: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c  ENAME]].** ^Appl
bca0: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f  ication can invo
bcb0: 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  ke the [SQLITE_F
bcc0: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
bcd0: 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  E] file-control.
bce0: 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74  ** to have SQLit
bcf0: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20  e generate a.** 
bd00: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
bd10: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  me using the sam
bd20: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74  e algorithm that
bd30: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20   is followed to 
bd40: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70  generate.** temp
bd50: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20  orary filenames 
bd60: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20  for TEMP tables 
bd70: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e  and other intern
bd80: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a  al uses.  The.**
bd90: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
bda0: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69   be a char** whi
bdb0: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65  ch will be fille
bdc0: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e  d with the filen
bdd0: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69  ame.** written i
bde0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
bdf0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
be00: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
be10: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a  e caller should.
be20: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ** invoke [sqlit
be30: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68  e3_free()] on th
be40: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69  e result to avoi
be50: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e  d a memory leak.
be60: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
be70: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
be80: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
be90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
bea0: 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
beb0: 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75  ol is used to qu
bec0: 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a  ery or set the.*
bed0: 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  * maximum number
bee0: 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77   of bytes that w
bef0: 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20  ill be used for 
bf00: 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f  memory-mapped I/
bf10: 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  O..** The argume
bf20: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
bf30: 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79  to a value of ty
bf40: 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  pe sqlite3_int64
bf50: 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61   that.** is an a
bf60: 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20  dvisory maximum 
bf70: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
bf80: 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d  in the file to m
bf90: 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a  emory map.  The.
bfa0: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76  ** pointer is ov
bfb0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
bfc0: 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54  he old value.  T
bfd0: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  he limit is not 
bfe0: 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68  changed if.** th
bff0: 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c  e value original
c000: 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73  ly pointed to is
c010: 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73   negative, and s
c020: 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69  o the current li
c030: 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71  mit .** can be q
c040: 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e  ueried by passin
c050: 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  g in a pointer t
c060: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  o a negative num
c070: 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69  ber.  This.** fi
c080: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le-control is us
c090: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
c0a0: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47   implement [PRAG
c0b0: 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a  MA mmap_size]..*
c0c0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c0d0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a  E_FCNTL_TRACE]].
c0e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c0f0: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65  CNTL_TRACE] file
c100: 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65   control provide
c110: 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72  s advisory infor
c120: 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65  mation.** to the
c130: 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20   VFS about what 
c140: 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72  the higher layer
c150: 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  s of the SQLite 
c160: 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e  stack are doing.
c170: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f  .** This file co
c180: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79  ntrol is used by
c190: 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69   some VFS activi
c1a0: 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d  ty tracing [shim
c1b0: 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  s]..** The argum
c1c0: 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65  ent is a zero-te
c1d0: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e  rminated string.
c1e0: 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20    Higher layers 
c1f0: 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  in the.** SQLite
c200: 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72   stack may gener
c210: 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66  ate instances of
c220: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
c230: 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51  ol if.** the [SQ
c240: 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54  LITE_USE_FCNTL_T
c250: 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
c260: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
c270: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  bled..**.** <li>
c280: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  [[SQLITE_FCNTL_H
c290: 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68  AS_MOVED]].** Th
c2a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c2b0: 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20  HAS_MOVED] file 
c2c0: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
c2d0: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
c2e0: 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  as a.** pointer 
c2f0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
c300: 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f  d it writes a bo
c310: 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20  olean into that 
c320: 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e  integer dependin
c330: 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  g.** on whether 
c340: 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20  or not the file 
c350: 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64  has been renamed
c360: 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65  , moved, or dele
c370: 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20  ted since it.** 
c380: 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64  was first opened
c390: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c3a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c3b0: 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a  _GET_HANDLE]].**
c3c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c3d0: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
c3e0: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  DLE] opcode can 
c3f0: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
c400: 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  n the.** underly
c410: 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20  ing native file 
c420: 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65  handle associate
c430: 64 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61  d with a file ha
c440: 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65  ndle.  This file
c450: 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65  .** control inte
c460: 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d  rprets its argum
c470: 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72  ent as a pointer
c480: 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c   to a native fil
c490: 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20  e handle and.** 
c4a0: 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c  writes the resul
c4b0: 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65  ting value there
c4c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c4d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c4e0: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a  _SET_HANDLE]].**
c4f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c500: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
c510: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  DLE] opcode is u
c520: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
c530: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
c540: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
c550: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
c560: 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69  d to swap the fi
c570: 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74  le handle with t
c580: 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65  he one.** pointe
c590: 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67  d to by the pArg
c5a0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73   argument.  This
c5b0: 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75   capability is u
c5c0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
c5d0: 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e  ng.** and only n
c5e0: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
c5f0: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
c600: 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64  _TEST is defined
c610: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c620: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c630: 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  LOCK]].** The [S
c640: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
c650: 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e  BLOCK] is a sign
c660: 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61  al to the VFS la
c670: 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68  yer that it migh
c680: 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67  t.** be advantag
c690: 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e  eous to block on
c6a0: 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f   the next WAL lo
c6b0: 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69  ck if the lock i
c6c0: 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c  s not immediatel
c6d0: 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20  y.** available. 
c6e0: 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74   The WAL subsyst
c6f0: 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73  em issues this s
c700: 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72  ignal during rar
c710: 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63  e.** circumstanc
c720: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  es in order to f
c730: 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74  ix a problem wit
c740: 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72  h priority inver
c750: 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  sion..** Applica
c760: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d  tions should <em
c770: 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68  >not</em> use th
c780: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e  is file-control.
c790: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c7a0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c7b0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c7c0: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20  E_FCNTL_ZIPVFS] 
c7d0: 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d  opcode is implem
c7e0: 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20  ented by zipvfs 
c7f0: 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a  only. All other.
c800: 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  ** VFS should re
c810: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
c820: 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70  OUND for this op
c830: 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  code..**.** <li>
c840: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  [[SQLITE_FCNTL_R
c850: 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  BU]].** The [SQL
c860: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f  ITE_FCNTL_RBU] o
c870: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
c880: 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63  nted by the spec
c890: 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a  ial VFS used by.
c8a0: 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e  ** the RBU exten
c8b0: 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20  sion only.  All 
c8c0: 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64  other VFS should
c8d0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
c8e0: 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74  OTFOUND for.** t
c8f0: 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a  his opcode.  .**
c900: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c910: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c920: 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49  MIC_WRITE]].** I
c930: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
c940: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
c950: 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72  _WRITE] opcode r
c960: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
c970: 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69  , then.** the fi
c980: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 69 73  le descriptor is
c990: 20 70 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63   placed in "batc
c9a0: 68 20 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77  h write mode", w
c9b0: 68 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c  hich.** means al
c9c0: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69  l subsequent wri
c9d0: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69  te operations wi
c9e0: 6c 6c 20 62 65 20 64 65 66 65 72 72 65 64 20 61  ll be deferred a
c9f0: 6e 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69  nd done.** atomi
ca00: 63 61 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78  cally at the nex
ca10: 74 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  t [SQLITE_FCNTL_
ca20: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
ca30: 49 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a  ITE].  Systems.*
ca40: 2a 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75  * that do not su
ca50: 70 70 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d  pport batch atom
ca60: 69 63 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72  ic writes will r
ca70: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54  eturn SQLITE_NOT
ca80: 46 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f  FOUND..** ^Follo
ca90: 77 69 6e 67 20 61 20 73 75 63 63 65 73 73 66 75  wing a successfu
caa0: 6c 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  l SQLITE_FCNTL_B
cab0: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
cac0: 45 20 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a  E and prior to.*
cad0: 2a 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53  * the closing [S
cae0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
caf0: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IT_ATOMIC_WRITE]
cb00: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   or.** [SQLITE_F
cb10: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
cb20: 4f 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c  OMIC_WRITE], SQL
cb30: 69 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a  ite will make.**
cb40: 20 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63   no VFS interfac
cb50: 65 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73  e calls on the s
cb60: 61 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  ame [sqlite3_fil
cb70: 65 5d 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  e] file descript
cb80: 6f 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72  or.** except for
cb90: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57   calls to the xW
cba0: 72 69 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20  rite method and 
cbb0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
cbc0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20   method.** with 
cbd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
cbe0: 5a 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20  ZE_HINT]..**.** 
cbf0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
cc00: 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  TL_COMMIT_ATOMIC
cc10: 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20  _WRITE]].** The 
cc20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
cc30: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
cc40: 45 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  E] opcode causes
cc50: 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70   all write.** op
cc60: 65 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74  erations since t
cc70: 68 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63  he previous succ
cc80: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a  essful call to .
cc90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
cca0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
ccb0: 49 54 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f  ITE] to be perfo
ccc0: 72 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e  rmed atomically.
ccd0: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f  .** This file co
cce0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
ccf0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64  QLITE_OK] if and
cd00: 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69   only if the wri
cd10: 74 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20  tes were.** all 
cd20: 70 65 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73  performed succes
cd30: 73 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20  sfully and have 
cd40: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74  been committed t
cd50: 6f 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f  o persistent sto
cd60: 72 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64  rage..** ^Regard
cd70: 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
cd80: 6f 72 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63  or not it is suc
cd90: 63 65 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69  cessful, this fi
cda0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73  le control takes
cdb0: 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73  .** the file des
cdc0: 63 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62  criptor out of b
cdd0: 61 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20  atch write mode 
cde0: 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73  so that all subs
cdf0: 65 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20  equent.** write 
ce00: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69  operations are i
ce10: 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e  ndependent..** ^
ce20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
ce30: 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f  r invoke SQLITE_
ce40: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
ce50: 4d 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75  MIC_WRITE withou
ce60: 74 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63  t.** a prior suc
ce70: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
ce80: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
ce90: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
cea0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
ceb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c  QLITE_FCNTL_ROLL
cec0: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54  BACK_ATOMIC_WRIT
ced0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
cee0: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
cef0: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  K_ATOMIC_WRITE] 
cf00: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c  opcode causes al
cf10: 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61  l write.** opera
cf20: 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20  tions since the 
cf30: 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73  previous success
cf40: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20  ful call to .** 
cf50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
cf60: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
cf70: 5d 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62  ] to be rolled b
cf80: 61 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69  ack..** ^This fi
cf90: 6c 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73  le control takes
cfa0: 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69   the file descri
cfb0: 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63  ptor out of batc
cfc0: 68 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20  h write mode.** 
cfd0: 73 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73  so that all subs
cfe0: 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65  equent write ope
cff0: 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65  rations are inde
d000: 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c  pendent..** ^SQL
d010: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
d020: 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e  nvoke SQLITE_FCN
d030: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
d040: 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74  IC_WRITE without
d050: 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63  .** a prior succ
d060: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
d070: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
d080: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
d090: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
d0a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f  LITE_FCNTL_LOCK_
d0b0: 54 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65  TIMEOUT]].** The
d0c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
d0d0: 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63  OCK_TIMEOUT] opc
d0e0: 6f 64 65 20 63 61 75 73 65 73 20 61 74 74 65 6d  ode causes attem
d0f0: 70 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  pts to obtain.**
d100: 20 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69   a file lock usi
d110: 6e 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20  ng the xLock or 
d120: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73  xShmLock methods
d130: 20 6f 66 20 74 68 65 20 56 46 53 20 74 6f 20 77   of the VFS to w
d140: 61 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f  ait.** for up to
d150: 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20   M milliseconds 
d160: 62 65 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20  before failing, 
d170: 77 68 65 72 65 20 4d 20 69 73 20 74 68 65 20 73  where M is the s
d180: 69 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e  ingle .** unsign
d190: 65 64 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d  ed integer param
d1a0: 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  eter..**.** <li>
d1b0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44  [[SQLITE_FCNTL_D
d1c0: 41 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a  ATA_VERSION]].**
d1d0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
d1e0: 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d  TL_DATA_VERSION]
d1f0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
d200: 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65  to detect change
d210: 73 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61  s to.** a databa
d220: 73 65 20 66 69 6c 65 2e 20 20 54 68 65 20 61 72  se file.  The ar
d230: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
d240: 74 65 72 20 74 6f 20 61 20 33 32 2d 62 69 74 20  ter to a 32-bit 
d250: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
d260: 2e 0a 2a 2a 20 54 68 65 20 22 64 61 74 61 20 76  ..** The "data v
d270: 65 72 73 69 6f 6e 22 20 66 6f 72 20 74 68 65 20  ersion" for the 
d280: 70 61 67 65 72 20 69 73 20 77 72 69 74 74 65 6e  pager is written
d290: 20 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e 74 65   into the pointe
d2a0: 72 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61 74 61  r.  The.** "data
d2b0: 20 76 65 72 73 69 6f 6e 22 20 63 68 61 6e 67 65   version" change
d2c0: 73 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 63  s whenever any c
d2d0: 68 61 6e 67 65 20 6f 63 63 75 72 73 20 74 6f 20  hange occurs to 
d2e0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
d2f0: 67 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  g.** database fi
d300: 6c 65 2c 20 65 69 74 68 65 72 20 74 68 72 6f 75  le, either throu
d310: 67 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  gh SQL statement
d320: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
d330: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
d340: 74 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67 68 20  tion or through 
d350: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d  transactions com
d360: 6d 69 74 74 65 64 20 62 79 20 73 65 70 61 72 61  mitted by separa
d370: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  te database.** c
d380: 6f 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73 73 69  onnections possi
d390: 62 6c 79 20 69 6e 20 6f 74 68 65 72 20 70 72 6f  bly in other pro
d3a0: 63 65 73 73 65 73 2e 20 54 68 65 20 5b 73 71 6c  cesses. The [sql
d3b0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
d3c0: 65 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  es()].** interfa
d3d0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
d3e0: 6f 20 66 69 6e 64 20 69 66 20 61 6e 79 20 64 61  o find if any da
d3f0: 74 61 62 61 73 65 20 6f 6e 20 74 68 65 20 63 6f  tabase on the co
d400: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 63 68 61  nnection has cha
d410: 6e 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61  nged,.** but tha
d420: 74 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70  t interface resp
d430: 6f 6e 64 73 20 74 6f 20 63 68 61 6e 67 65 73 20  onds to changes 
d440: 6f 6e 20 54 45 4d 50 20 61 73 20 77 65 6c 6c 20  on TEMP as well 
d450: 61 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73  as MAIN and does
d460: 0a 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64 65 20  .** not provide 
d470: 61 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64  a mechanism to d
d480: 65 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  etect changes to
d490: 20 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73   MAIN only.  Als
d4a0: 6f 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  o, the.** [sqlit
d4b0: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
d4c0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
d4d0: 73 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e  sponds to intern
d4e0: 61 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20  al changes only 
d4f0: 61 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61  and.** omits cha
d500: 6e 67 65 73 20 6d 61 64 65 20 62 79 20 6f 74 68  nges made by oth
d510: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
d520: 65 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  ections.  The.**
d530: 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65   [PRAGMA data_ve
d540: 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70  rsion] command p
d550: 72 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69  rovide a mechani
d560: 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61  sm to detect cha
d570: 6e 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e  nges to.** a sin
d580: 67 6c 65 20 61 74 74 61 63 68 65 64 20 64 61 74  gle attached dat
d590: 61 62 61 73 65 20 74 68 61 74 20 6f 63 63 75 72  abase that occur
d5a0: 20 64 75 65 20 74 6f 20 6f 74 68 65 72 20 64 61   due to other da
d5b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d5c0: 6e 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73  ns,.** but omits
d5d0: 20 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65   changes impleme
d5e0: 6e 74 65 64 20 62 79 20 74 68 65 20 64 61 74 61  nted by the data
d5f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
d600: 6f 6e 20 77 68 69 63 68 20 69 74 20 69 73 0a 2a  on which it is.*
d610: 2a 20 63 61 6c 6c 65 64 2e 20 20 54 68 69 73 20  * called.  This 
d620: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
d630: 74 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69  the only mechani
d640: 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61  sm to detect cha
d650: 6e 67 65 73 20 74 68 61 74 0a 2a 2a 20 68 61 70  nges that.** hap
d660: 70 65 6e 20 65 69 74 68 65 72 20 69 6e 74 65 72  pen either inter
d670: 6e 61 6c 6c 79 20 6f 72 20 65 78 74 65 72 6e 61  nally or externa
d680: 6c 6c 79 20 61 6e 64 20 74 68 61 74 20 61 72 65  lly and that are
d690: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
d6a0: 0a 2a 2a 20 61 20 70 61 72 74 69 63 75 6c 61 72  .** a particular
d6b0: 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
d6c0: 73 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  se..** </ul>.*/.
d6d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d6e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
d6f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
d700: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d710: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
d720: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
d730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d740: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
d750: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
d760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d770: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
d780: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
d790: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d7a0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
d7b0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
d7c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d7d0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
d7e0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
d7f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
d800: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
d810: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
d820: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
d830: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
d840: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
d850: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
d860: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
d870: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
d880: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
d890: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
d8a0: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
d8b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
d8c0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
d8d0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
d8e0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
d8f0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
d900: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
d910: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
d920: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
d930: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
d940: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
d950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
d960: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
d970: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
d980: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
d990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d9a0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
d9b0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
d9c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d9d0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
d9e0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
d9f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
da00: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
da10: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
da20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
da30: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
da40: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
da50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
da60: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
da70: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
da80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
da90: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
daa0: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
dab0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
dac0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
dad0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
dae0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
daf0: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
db00: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
db10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49   SQLITE_FCNTL_ZI
db20: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20  PVFS            
db30: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20       25.#define 
db40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
db50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
db60: 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53      26.#define S
db70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
db80: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
db90: 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51     27.#define SQ
dba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
dbb0: 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  AL_POINTER      
dbc0: 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    28.#define SQL
dbd0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
dbe0: 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20  GET_HANDLE      
dbf0: 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   29.#define SQLI
dc00: 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20  TE_FCNTL_PDB    
dc10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
dc20: 33 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  30.#define SQLIT
dc30: 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54  E_FCNTL_BEGIN_AT
dc40: 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20 20 33  OMIC_WRITE     3
dc50: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
dc60: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
dc70: 4f 4d 49 43 5f 57 52 49 54 45 20 20 20 20 33 32  OMIC_WRITE    32
dc80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc90: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41  FCNTL_ROLLBACK_A
dca0: 54 4f 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a  TOMIC_WRITE  33.
dcb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dcc0: 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55  CNTL_LOCK_TIMEOU
dcd0: 54 20 20 20 20 20 20 20 20 20 20 20 33 34 0a 23  T           34.#
dce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dcf0: 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e  NTL_DATA_VERSION
dd00: 20 20 20 20 20 20 20 20 20 20 20 33 35 0a 23 64             35.#d
dd10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dd20: 54 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 20 20  TL_SIZE_LIMIT   
dd30: 20 20 20 20 20 20 20 20 20 20 33 36 0a 0a 2f 2a            36../*
dd40: 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65   deprecated name
dd50: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
dd60: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
dd70: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
dd80: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b  E_FCNTL_GET_LOCK
dd90: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
dda0: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
ddb0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
ddc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
ddd0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23  _LOCKPROXYFILE.#
dde0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
ddf0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
de00: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
de10: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f  L_LAST_ERRNO.../
de20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
de30: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
de40: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
de50: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
de60: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
de70: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
de80: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
de90: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
dea0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
deb0: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
dec0: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
ded0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
dee0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
def0: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
df00: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
df10: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
df20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
df30: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
df40: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
df50: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
df60: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
df70: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
df80: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
df90: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
dfa0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
dfb0: 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78  REF: Loadable Ex
dfc0: 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a  tension Thunk.**
dfd0: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
dfe0: 20 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69   the opaque sqli
dff0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
e000: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61   structure is pa
e010: 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74  ssed as.** the t
e020: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
e030: 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f  o entry points o
e040: 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65  f [loadable exte
e050: 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a  nsions].  This.*
e060: 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74  * structure must
e070: 20 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e   be typedefed in
e080: 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61   order to work a
e090: 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77  round compiler w
e0a0: 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f  arnings.** on so
e0b0: 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f  me platforms..*/
e0c0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
e0d0: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
e0e0: 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69  ines sqlite3_api
e0f0: 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a  _routines;../*.*
e100: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
e110: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
e120: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
e130: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
e140: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
e150: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
e160: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
e170: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
e180: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
e190: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
e1a0: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
e1b0: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
e1c0: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
e1d0: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
e1e0: 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65  le system".  See
e1f0: 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56  .** the [VFS | V
e200: 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  FS documentation
e210: 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e  ] for further in
e220: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
e230: 20 54 68 65 20 56 46 53 20 69 6e 74 65 72 66 61   The VFS interfa
e240: 63 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20  ce is sometimes 
e250: 65 78 74 65 6e 64 65 64 20 62 79 20 61 64 64 69  extended by addi
e260: 6e 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f  ng new methods o
e270: 6e 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20  nto.** the end. 
e280: 20 45 61 63 68 20 74 69 6d 65 20 73 75 63 68 20   Each time such 
e290: 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63  an extension occ
e2a0: 75 72 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f  urs, the iVersio
e2b0: 6e 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e  n field.** is in
e2c0: 63 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20  cremented.  The 
e2d0: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73  iVersion value s
e2e0: 74 61 72 74 65 64 20 6f 75 74 20 61 73 20 31 20  tarted out as 1 
e2f0: 69 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65  in.** SQLite [ve
e300: 72 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20  rsion 3.5.0] on 
e310: 5b 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20  [dateof:3.5.0], 
e320: 74 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74  then increased t
e330: 6f 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69  o 2.** with SQLi
e340: 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e  te [version 3.7.
e350: 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e  0] on [dateof:3.
e360: 37 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69  7.0], and then i
e370: 6e 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33  ncreased.** to 3
e380: 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65   with SQLite [ve
e390: 72 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20  rsion 3.7.6] on 
e3a0: 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20  [dateof:3.7.6]. 
e3b0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
e3c0: 64 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70  ds.** may be app
e3d0: 65 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c  ended to the sql
e3e0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
e3f0: 61 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e  and the iVersion
e400: 20 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e   value.** may in
e410: 63 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20  crease again in 
e420: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
e430: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f  of SQLite..** No
e440: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
e450: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
e460: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
e470: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
e480: 65 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f  e transition fro
e490: 6d 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72  m.** SQLite [ver
e4a0: 73 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b  sion 3.5.9] to [
e4b0: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f  version 3.6.0] o
e4c0: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d  n [dateof:3.6.0]
e4d0: 0a 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20  .** and yet the 
e4e0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
e4f0: 61 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e  as not modified.
e500: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
e510: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
e520: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
e530: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
e540: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
e550: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
e560: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
e570: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
e580: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
e590: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
e5a0: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
e5b0: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
e5c0: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
e5d0: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
e5e0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
e5f0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
e600: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
e610: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
e620: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
e630: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
e640: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
e650: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
e660: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
e670: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
e680: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
e690: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
e6a0: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
e6b0: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
e6c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
e6d0: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
e6e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e6f0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
e700: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
e710: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
e720: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
e730: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
e740: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
e750: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
e760: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
e770: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
e780: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
e790: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
e7a0: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
e7b0: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
e7c0: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
e7d0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
e7e0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
e7f0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
e800: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
e810: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
e820: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
e830: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
e840: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
e850: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
e860: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
e870: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
e880: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
e890: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
e8a0: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
e8b0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
e8c0: 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e  vfs.xOpen]].** ^
e8d0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
e8e0: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
e8f0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
e900: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
e910: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
e920: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
e930: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
e940: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
e950: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
e960: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
e970: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
e980: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
e990: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
e9a0: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
e9b0: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
e9c0: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
e9d0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
e9e0: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61  ore than.** 11 a
e9f0: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
ea00: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
ea10: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
ea20: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
ea30: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
ea40: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
ea50: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
ea60: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
ea70: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
ea80: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
ea90: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
eaa0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
eab0: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
eac0: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
ead0: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
eae0: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
eaf0: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
eb00: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
eb10: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
eb20: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
eb30: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
eb40: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
eb50: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
eb60: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
eb70: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
eb80: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
eb90: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
eba0: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
ebb0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
ebc0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
ebd0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
ebe0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
ebf0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
ec00: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
ec10: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
ec20: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
ec30: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
ec40: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
ec50: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
ec60: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
ec70: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
ec80: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
ec90: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
eca0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
ecb0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
ecc0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
ecd0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
ece0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
ecf0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
ed00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
ed10: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
ed20: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
ed30: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
ed40: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
ed50: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
ed60: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
ed70: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
ed80: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
ed90: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
eda0: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
edb0: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
edc0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
edd0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
ede0: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
edf0: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
ee00: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
ee10: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
ee20: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ee30: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
ee40: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ee50: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
ee60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ee70: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
ee80: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ee90: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
eea0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
eeb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
eec0: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
eed0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
eee0: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
eef0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ef00: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
ef10: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ef20: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
ef30: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
ef40: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
ef50: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
ef60: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
ef70: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
ef80: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
ef90: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
efa0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
efb0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
efc0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
efd0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
efe0: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
eff0: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
f000: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
f010: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
f020: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
f030: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
f040: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
f050: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
f060: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
f070: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
f080: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
f090: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
f0a0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f0b0: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
f0c0: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
f0d0: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
f0e0: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
f0f0: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
f100: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
f110: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
f120: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
f130: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
f140: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
f150: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
f160: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
f170: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
f180: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
f190: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
f1a0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
f1b0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
f1c0: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
f1d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
f1e0: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
f1f0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
f200: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f210: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
f220: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
f230: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
f240: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
f250: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
f260: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
f270: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
f280: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
f290: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
f2a0: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
f2b0: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
f2c0: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
f2d0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
f2e0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
f2f0: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
f300: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
f310: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
f320: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
f330: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
f340: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
f350: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
f360: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
f370: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
f380: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
f390: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
f3a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
f3b0: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
f3c0: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
f3d0: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
f3e0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
f3f0: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
f400: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
f410: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
f420: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
f430: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
f440: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
f450: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
f460: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
f470: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
f480: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
f490: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
f4a0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
f4b0: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
f4c0: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
f4d0: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
f4e0: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
f4f0: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
f500: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
f510: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
f520: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
f530: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
f540: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
f550: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
f560: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
f570: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
f580: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
f590: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
f5a0: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
f5b0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
f5c0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
f5d0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
f5e0: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
f5f0: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
f600: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
f610: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
f620: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
f630: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
f640: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
f650: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
f660: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
f670: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
f680: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
f690: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
f6a0: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
f6b0: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
f6c0: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
f6d0: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
f6e0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
f6f0: 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a  3_vfs.xAccess]].
f700: 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72  ** ^The flags ar
f710: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
f720: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
f730: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
f740: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
f750: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
f760: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
f770: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f780: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
f790: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
f7a0: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
f7b0: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
f7c0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f7d0: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
f7e0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
f7f0: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
f800: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
f810: 43 43 45 53 53 5f 52 45 41 44 0a 2a 2a 20 66 6c  CCESS_READ.** fl
f820: 61 67 20 69 73 20 6e 65 76 65 72 20 61 63 74 75  ag is never actu
f830: 61 6c 6c 79 20 75 73 65 64 20 61 6e 64 20 69 73  ally used and is
f840: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
f850: 20 69 6e 20 74 68 65 20 62 75 69 6c 74 2d 69 6e   in the built-in
f860: 0a 2a 2a 20 56 46 53 65 73 20 6f 66 20 53 51 4c  .** VFSes of SQL
f870: 69 74 65 2e 20 20 54 68 65 20 66 69 6c 65 20 69  ite.  The file i
f880: 73 20 6e 61 6d 65 64 20 62 79 20 74 68 65 20 73  s named by the s
f890: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 61  econd argument a
f8a0: 6e 64 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  nd can be a.** d
f8b0: 69 72 65 63 74 6f 72 79 2e 20 54 68 65 20 78 41  irectory. The xA
f8c0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 72 65 74  ccess method ret
f8d0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
f8e0: 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 73   on success or s
f8f0: 6f 6d 65 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  ome.** non-zero 
f900: 65 72 72 6f 72 20 63 6f 64 65 20 69 66 20 74 68  error code if th
f910: 65 72 65 20 69 73 20 61 6e 20 49 2f 4f 20 65 72  ere is an I/O er
f920: 72 6f 72 20 6f 72 20 69 66 20 74 68 65 20 6e 61  ror or if the na
f930: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 69 6c  me of.** the fil
f940: 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 73  e given in the s
f950: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
f960: 73 20 69 6c 6c 65 67 61 6c 2e 20 20 49 66 20 53  s illegal.  If S
f970: 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 69 73 20 72  QLITE_OK.** is r
f980: 65 74 75 72 6e 65 64 2c 20 74 68 65 6e 20 6e 6f  eturned, then no
f990: 6e 2d 7a 65 72 6f 20 6f 72 20 7a 65 72 6f 20 69  n-zero or zero i
f9a0: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  s written into *
f9b0: 70 52 65 73 4f 75 74 20 74 6f 20 69 6e 64 69 63  pResOut to indic
f9c0: 61 74 65 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ate.** whether o
f9d0: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 69  r not the file i
f9e0: 73 20 61 63 63 65 73 73 69 62 6c 65 2e 20 20 0a  s accessible.  .
f9f0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
fa00: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
fa10: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
fa20: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
fa30: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
fa40: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
fa50: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
fa60: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
fa70: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
fa80: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
fa90: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
faa0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
fab0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
fac0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
fad0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
fae0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
faf0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
fb00: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
fb10: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
fb20: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
fb30: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
fb40: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
fb50: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
fb60: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
fb70: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
fb80: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
fb90: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
fba0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
fbb0: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
fbc0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
fbd0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
fbe0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
fbf0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
fc00: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
fc10: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
fc20: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
fc30: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
fc40: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
fc50: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
fc60: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
fc70: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
fc80: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
fc90: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
fca0: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
fcb0: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
fcc0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
fcd0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
fce0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
fcf0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
fd00: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
fd10: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
fd20: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
fd30: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
fd40: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
fd50: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
fd60: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
fd70: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
fd80: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
fd90: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
fda0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
fdb0: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
fdc0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
fdd0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
fde0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
fdf0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
fe00: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
fe10: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
fe20: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
fe30: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
fe40: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
fe50: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
fe60: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
fe70: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
fe80: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
fe90: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
fea0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
feb0: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
fec0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
fed0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
fee0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
fef0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
ff00: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
ff10: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
ff20: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
ff30: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
ff40: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
ff50: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
ff60: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
ff70: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
ff80: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
ff90: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
ffa0: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
ffb0: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
ffc0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
ffd0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
ffe0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
fff0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
10000 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
10010 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
10020 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
10030 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
10040 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
10050 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
10060 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
10070 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
10080 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
10090 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
100a0 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
100b0 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
100c0 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
100d0 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
100e0 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
100f0 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
10100 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
10110 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
10120 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
10130 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
10140 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
10150 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
10160 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
10170 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
10180 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
10190 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
101a0 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
101b0 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
101c0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
101d0 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
101e0 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
101f0 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
10200 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
10210 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
10220 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
10230 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
10240 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
10250 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
10260 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
10270 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
10280 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
10290 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
102a0 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
102b0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
102c0 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
102d0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
102e0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
102f0 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
10300 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
10310 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
10320 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
10330 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
10340 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
10350 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
10360 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
10370 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
10380 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
10390 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
103a0 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
103b0 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
103c0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
103d0 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
103e0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
103f0 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
10400 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
10410 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
10420 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
10430 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
10440 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
10450 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
10460 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
10470 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
10480 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
10490 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
104a0 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
104b0 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
104c0 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
104d0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
104e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
104f0 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
10500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
10510 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
10520 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
10530 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
10540 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10550 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
10560 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
10570 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
10580 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10590 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
105a0 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
105b0 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
105c0 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
105d0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
105e0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
105f0 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
10600 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
10610 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
10620 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10630 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
10640 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
10650 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10660 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
10670 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
10680 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
10690 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
106a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
106b0 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
106c0 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
106d0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
106e0 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
106f0 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
10700 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
10710 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
10720 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
10730 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
10740 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
10750 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
10760 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
10770 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
10780 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
10790 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
107a0 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
107b0 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
107c0 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
107d0 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
107e0 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
107f0 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
10800 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
10810 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
10820 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
10830 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
10840 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
10850 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
10860 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
10870 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
10880 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
10890 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
108a0 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
108b0 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
108c0 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
108d0 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
108e0 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
108f0 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
10900 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
10910 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
10920 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10930 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
10940 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
10950 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
10960 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
10970 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
10980 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
10990 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
109a0 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
109b0 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
109c0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
109d0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
109e0 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
109f0 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
10a00 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
10a10 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
10a20 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
10a30 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
10a40 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
10a50 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
10a60 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
10a70 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
10a80 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
10a90 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
10aa0 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
10ab0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
10ac0 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
10ad0 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
10ae0 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
10af0 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
10b00 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
10b10 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
10b20 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
10b30 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
10b40 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
10b50 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
10b60 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
10b70 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
10b80 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10b90 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
10ba0 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
10bb0 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
10bc0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10bd0 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
10be0 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
10bf0 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
10c00 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
10c10 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
10c20 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10c30 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10c40 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
10c50 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
10c60 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
10c70 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
10c80 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
10c90 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
10ca0 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
10cb0 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
10cc0 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
10cd0 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
10ce0 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
10cf0 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
10d00 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
10d10 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
10d20 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
10d30 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
10d40 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
10d50 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
10d60 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10d70 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
10d80 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
10d90 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10da0 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
10db0 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
10dc0 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
10dd0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10de0 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
10df0 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
10e00 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
10e10 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
10e20 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
10e30 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
10e40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
10e50 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
10e60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10e70 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10e80 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
10e90 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
10ea0 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
10eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
10ec0 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
10ed0 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
10ee0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10ef0 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
10f00 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
10f10 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
10f20 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
10f30 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
10f40 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
10f50 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
10f60 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
10f70 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
10f80 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
10f90 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
10fa0 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
10fb0 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
10fc0 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
10fd0 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
10fe0 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
10ff0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
11000 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
11010 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
11020 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
11030 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
11040 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
11050 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
11060 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
11070 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
11080 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
11090 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
110a0 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
110b0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
110c0 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
110d0 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
110e0 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
110f0 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
11100 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
11110 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
11120 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
11130 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
11140 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
11150 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
11160 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
11170 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
11180 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
11190 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
111a0 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
111b0 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
111c0 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
111d0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
111e0 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
111f0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
11200 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
11210 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
11220 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
11230 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
11240 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
11250 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
11260 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
11270 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
11280 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
11290 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
112a0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
112b0 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
112c0 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
112d0 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
112e0 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
112f0 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
11300 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
11310 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
11320 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
11330 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
11340 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
11350 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
11360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11370 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
11380 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
11390 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
113a0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
113b0 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
113c0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
113d0 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
113e0 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
113f0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
11400 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
11410 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
11420 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
11430 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
11440 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
11450 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
11460 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
11470 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
11480 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
11490 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
114a0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
114b0 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
114c0 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
114d0 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
114e0 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
114f0 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
11500 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
11510 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
11520 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
11530 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
11540 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11550 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
11560 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
11570 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
11580 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
11590 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
115a0 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
115b0 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
115c0 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
115d0 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
115e0 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
115f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
11600 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
11610 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
11620 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11630 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
11640 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
11650 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
11660 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
11670 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
11680 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
11690 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
116a0 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
116b0 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
116c0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
116d0 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
116e0 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
116f0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
11700 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
11710 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
11720 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
11730 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
11740 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
11750 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
11760 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11770 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
11780 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
11790 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
117a0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
117b0 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
117c0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
117d0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
117e0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
117f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
11800 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
11810 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11820 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
11830 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11840 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
11850 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
11860 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
11870 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
11880 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
11890 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
118a0 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
118b0 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
118c0 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
118d0 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
118e0 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
118f0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
11900 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
11910 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
11920 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
11930 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
11940 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
11950 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
11960 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
11970 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
11980 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
11990 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
119a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
119b0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
119c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
119d0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
119e0 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
119f0 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
11a00 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11a10 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
11a20 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
11a30 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
11a40 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
11a50 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
11a60 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
11a70 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
11a80 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
11a90 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
11aa0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
11ab0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
11ac0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11ad0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
11ae0 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
11af0 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
11b00 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
11b10 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
11b20 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
11b30 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
11b40 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
11b50 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11b60 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
11b70 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
11b80 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
11b90 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
11ba0 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
11bb0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
11bc0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
11bd0 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
11be0 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
11bf0 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
11c00 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
11c10 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
11c20 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
11c30 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
11c40 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11c50 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
11c60 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
11c70 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
11c80 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
11c90 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
11ca0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
11cb0 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
11cc0 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
11cd0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
11ce0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
11cf0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
11d00 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
11d10 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
11d20 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11d30 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
11d40 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
11d50 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
11d60 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
11d70 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
11d80 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11d90 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
11da0 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
11db0 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
11dc0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
11dd0 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
11de0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
11df0 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
11e00 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
11e10 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
11e20 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
11e30 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11e40 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
11e50 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
11e60 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
11e70 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
11e80 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
11e90 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
11ea0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
11eb0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
11ec0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
11ed0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
11ee0 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
11ef0 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
11f00 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
11f10 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
11f20 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
11f30 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
11f40 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
11f50 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
11f60 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
11f70 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
11f80 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
11f90 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
11fa0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
11fb0 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
11fc0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
11fd0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
11fe0 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
11ff0 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
12000 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
12010 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
12020 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
12030 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
12040 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12050 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
12060 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
12070 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
12080 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
12090 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
120a0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
120b0 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
120c0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
120d0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
120e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
120f0 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
12100 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
12110 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
12120 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
12130 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
12140 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
12150 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12160 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
12170 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
12180 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
12190 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
121a0 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
121b0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
121c0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
121d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
121e0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
121f0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
12200 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
12210 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
12220 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
12230 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
12240 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
12250 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
12260 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
12270 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
12280 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
12290 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
122a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
122b0 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
122c0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
122d0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
122e0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
122f0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
12300 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
12310 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
12320 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
12330 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
12340 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
12350 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
12360 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
12370 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
12380 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
12390 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
123a0 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
123b0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
123c0 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
123d0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
123e0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
123f0 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
12400 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
12410 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
12420 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
12430 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
12440 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
12450 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
12460 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
12470 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
12480 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
12490 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
124a0 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
124b0 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
124c0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
124d0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
124e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
124f0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
12500 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
12510 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
12520 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
12530 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
12540 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
12550 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
12560 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
12570 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
12580 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
12590 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
125a0 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
125b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
125c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
125d0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
125e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
125f0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
12600 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
12610 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
12620 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
12630 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
12640 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
12650 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
12660 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
12670 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
12680 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
12690 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
126a0 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
126b0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
126c0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
126d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
126e0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
126f0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
12700 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
12710 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
12720 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
12730 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
12740 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
12750 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
12760 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
12770 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
12780 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
12790 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
127a0 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
127b0 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
127c0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
127d0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
127e0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
127f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
12800 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
12810 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
12820 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12830 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
12840 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
12850 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
12860 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
12870 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
12880 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
12890 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
128a0 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
128b0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
128c0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
128d0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
128e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
128f0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
12900 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
12910 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
12920 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
12930 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
12940 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
12950 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
12960 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
12970 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
12980 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
12990 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
129a0 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
129b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
129c0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
129d0 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
129e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
129f0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
12a00 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
12a10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
12a20 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
12a30 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
12a40 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
12a50 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
12a60 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
12a70 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
12a80 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
12a90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12aa0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
12ab0 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
12ac0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
12ad0 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
12ae0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
12af0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
12b00 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
12b10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
12b20 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
12b30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
12b40 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
12b50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
12b60 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
12b70 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
12b80 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
12b90 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
12ba0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
12bb0 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
12bc0 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
12bd0 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
12be0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
12bf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12c00 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
12c10 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
12c20 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
12c30 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
12c40 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
12c50 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
12c60 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
12c70 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
12c80 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
12c90 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
12ca0 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
12cb0 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
12cc0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
12cd0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
12ce0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
12cf0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
12d00 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
12d10 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
12d20 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
12d30 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12d40 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
12d50 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
12d60 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
12d70 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
12d80 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12d90 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
12da0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
12db0 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
12dc0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
12dd0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
12de0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12df0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
12e00 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
12e10 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
12e20 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
12e30 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
12e40 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
12e50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12e60 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
12e70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12e80 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
12e90 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
12ea0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12eb0 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
12ec0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
12ed0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
12ee0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
12ef0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
12f00 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
12f10 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
12f20 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
12f30 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
12f40 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
12f50 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
12f60 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
12f70 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
12f80 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
12f90 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
12fa0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
12fb0 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
12fc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
12fd0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
12fe0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
12ff0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
13000 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
13010 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
13020 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
13030 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
13040 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
13050 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
13060 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
13070 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
13080 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13090 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
130a0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
130b0 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
130c0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
130d0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
130e0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
130f0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
13100 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
13110 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
13120 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
13130 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
13140 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
13150 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
13160 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
13170 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
13180 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
13190 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
131a0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
131b0 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
131c0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
131d0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
131e0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
131f0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
13200 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
13210 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
13220 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
13230 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
13240 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
13250 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
13260 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
13270 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
13280 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
13290 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
132a0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
132b0 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
132c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
132d0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
132e0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
132f0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
13300 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
13310 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
13320 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
13330 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
13340 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
13350 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
13360 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
13370 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
13380 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
13390 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
133a0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
133b0 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
133c0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
133d0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
133e0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
133f0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
13400 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
13410 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
13420 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
13430 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
13440 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
13450 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
13460 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
13470 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
13480 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
13490 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
134a0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
134b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
134c0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
134d0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
134e0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
134f0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
13500 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
13510 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
13520 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
13530 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
13540 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
13550 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
13560 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
13570 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
13580 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
13590 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
135a0 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
135b0 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
135c0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
135d0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
135e0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
135f0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
13600 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
13610 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
13620 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
13630 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
13640 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
13650 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
13660 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
13670 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
13680 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
13690 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
136a0 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
136b0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
136c0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
136d0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
136e0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
136f0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
13700 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
13710 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
13720 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
13730 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
13740 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
13750 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
13760 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
13770 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
13780 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
13790 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
137a0 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
137b0 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
137c0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
137d0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
137e0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
137f0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
13800 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
13810 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13820 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
13830 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
13840 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
13850 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
13860 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
13870 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
13880 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
13890 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
138a0 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
138b0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
138c0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
138d0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
138e0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
138f0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
13900 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
13910 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
13920 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
13930 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
13940 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
13950 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
13960 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
13970 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
13980 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
13990 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
139a0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
139b0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
139c0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
139d0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
139e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
139f0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
13a00 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
13a10 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
13a20 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
13a30 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
13a40 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
13a50 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
13a60 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
13a70 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
13a80 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
13a90 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
13aa0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
13ab0 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
13ac0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
13ad0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
13ae0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
13af0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
13b00 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
13b10 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
13b20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
13b30 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
13b40 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
13b50 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
13b60 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
13b70 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
13b80 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
13b90 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
13ba0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
13bb0 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
13bc0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13bd0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
13be0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
13bf0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
13c00 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
13c10 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
13c20 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
13c30 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
13c40 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
13c50 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
13c60 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
13c70 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
13c80 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
13c90 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
13ca0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13cb0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
13cc0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
13cd0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13ce0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
13cf0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
13d00 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
13d10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13d20 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
13d30 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
13d40 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
13d50 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
13d60 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13d70 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
13d80 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
13d90 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
13da0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
13db0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
13dc0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13dd0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
13de0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
13df0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
13e00 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
13e10 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
13e20 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
13e30 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
13e40 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
13e50 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
13e60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13e70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
13e80 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
13e90 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13ea0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
13eb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13ec0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
13ed0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
13ee0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
13ef0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
13f00 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
13f10 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13f20 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13f30 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
13f40 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
13f50 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
13f60 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
13f70 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
13f80 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
13f90 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
13fa0 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
13fb0 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
13fc0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13fd0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13fe0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13ff0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14000 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14010 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14020 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
14030 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
14040 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
14050 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
14060 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
14070 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
14080 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
14090 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
140a0 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
140b0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
140c0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
140d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
140e0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
140f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14100 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14110 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
14120 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
14130 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
14140 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
14150 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
14160 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
14170 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
14180 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
14190 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
141a0 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
141b0 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
141c0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
141d0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
141e0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
141f0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
14200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
14210 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
14220 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
14230 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
14240 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
14250 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
14260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
14270 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
14280 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
14290 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
142a0 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
142b0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
142c0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
142d0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
142e0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
142f0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
14300 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
14310 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
14320 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
14330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14340 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
14350 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
14360 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14370 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14380 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14390 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
143a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
143b0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
143c0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
143d0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
143e0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
143f0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
14400 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14410 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
14420 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
14430 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
14440 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
14450 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
14460 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14470 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
14480 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
14490 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
144a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
144b0 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
144c0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
144d0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
144e0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
144f0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14500 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14510 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
14520 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
14530 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
14540 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
14550 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
14560 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
14570 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
14580 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14590 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
145a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
145b0 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
145c0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
145d0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
145e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
145f0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
14600 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
14610 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
14620 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
14630 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
14640 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
14650 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
14660 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
14670 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
14680 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
14690 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
146a0 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
146b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
146c0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
146d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
146e0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
146f0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
14700 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
14710 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14720 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14730 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14740 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14750 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14760 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14770 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
14780 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
14790 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
147a0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
147b0 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
147c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
147d0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
147e0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
147f0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
14800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14810 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
14820 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
14830 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14840 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
14850 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14860 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
14870 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14880 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
14890 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
148a0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
148b0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
148c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
148d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
148e0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
148f0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14900 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
14910 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
14920 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
14930 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
14940 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
14950 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
14960 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
14970 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
14980 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
14990 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
149a0 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
149b0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
149c0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
149d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
149e0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
149f0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
14a00 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
14a10 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
14a20 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
14a30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14a40 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
14a50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14a60 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
14a70 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14a80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
14a90 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
14aa0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14ab0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14ac0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14ad0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14ae0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
14af0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
14b00 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
14b10 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
14b20 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
14b30 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
14b40 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
14b50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14b60 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
14b70 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
14b80 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
14b90 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
14ba0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14bb0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
14bc0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
14bd0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
14be0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14bf0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
14c00 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
14c10 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
14c20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14c30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
14c40 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  LL_MALLOC]] <dt>
14c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
14c60 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  ALL_MALLOC</dt>.
14c70 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
14c80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
14c90 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  _MALLOC option t
14ca0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
14cb0 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20  ment of.** type 
14cc0 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
14cd0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
14ce0 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f  hich if true pro
14cf0 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a  vides a hint to.
14d00 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  ** SQLite that i
14d10 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c  t should avoid l
14d20 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  arge memory allo
14d30 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69  cations if possi
14d40 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ble..** SQLite w
14d50 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69  ill run faster i
14d60 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20  f it is free to 
14d70 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72  make large memor
14d80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a  y allocations,.*
14d90 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69  * but some appli
14da0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65  cation might pre
14db0 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65  fer to run slowe
14dc0 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f  r in exchange fo
14dd0 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  r.** guarantees 
14de0 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61  about memory fra
14df0 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  gmentation that 
14e00 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20  are possible if 
14e10 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  large.** allocat
14e20 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64  ions are avoided
14e30 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
14e40 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a  normally off..**
14e50 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14e60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
14e70 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
14e80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14e90 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
14ea0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
14eb0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
14ec0 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
14ed0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
14ee0 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
14ef0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
14f00 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
14f10 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
14f20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
14f30 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
14f40 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14f50 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
14f60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14f70 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
14f80 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
14f90 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
14fa0 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
14fb0 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
14fc0 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
14fd0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
14fe0 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
14ff0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
15000 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
15010 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
15020 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
15030 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
15040 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
15050 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
15060 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
15070 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
15080 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
15090 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
150a0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
150b0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
150c0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
150d0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
150e0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
150f0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
15100 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
15110 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
15120 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
15130 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15140 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
15150 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15160 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
15170 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
15180 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
15190 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ption is no long
151a0 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64  er used..** </dd
151b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
151c0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
151d0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
151e0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
151f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
15200 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15210 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
15220 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d   specifies a mem
15230 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74  ory pool.** that
15240 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
15250 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
15260 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
15270 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
15280 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
15290 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
152a0 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
152b0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e  on option is a n
152c0 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69  o-op if an appli
152d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
152e0 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
152f0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
15300 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
15310 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15320 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72  ACHE2]..** ^Ther
15330 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
15340 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
15350 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15360 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  : A pointer to.*
15370 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  * 8-byte aligned
15380 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20   memory (pMem), 
15390 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
153a0 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
153b0 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
153c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68  e number of cach
153d0 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20  e lines (N)..** 
153e0 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
153f0 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
15400 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
15410 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
15420 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
15430 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
15440 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
15450 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
15460 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
15470 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
15480 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
15490 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
154a0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
154b0 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
154c0 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54  ned using [SQLIT
154d0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
154e0 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69  HDRSZ]..** ^It i
154f0 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
15500 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
15510 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
15520 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
15530 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
15540 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
15550 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75  The pMem.** argu
15560 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74  ment must be eit
15570 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
15580 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  er or a pointer 
15590 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
155a0 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66  aligned block of
155b0 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65   memory of at le
155c0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20  ast sz*N bytes, 
155d0 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62  otherwise.** sub
155e0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
155f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
15600 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20  * ^When pMem is 
15610 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
15620 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20   will strive to 
15630 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
15640 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61  rovided.** to sa
15650 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65  tisfy page cache
15660 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20   needs, falling 
15670 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33  back to [sqlite3
15680 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a  _malloc()] if.**
15690 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69   a page cache li
156a0 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61  ne is larger tha
156b0 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66  n sz bytes or if
156c0 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d   all of the pMem
156d0 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78   buffer.** is ex
156e0 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20  hausted..** ^If 
156f0 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64  pMem is NULL and
15700 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20   N is non-zero, 
15710 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61  then each databa
15720 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
15730 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c   does an initial
15740 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e   bulk allocation
15750 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
15760 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b  memory.** from [
15770 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15780 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72  ] sufficient for
15790 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69   N cache lines i
157a0 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20  f N is positive 
157b0 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e  or.** of -1024*N
157c0 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e   bytes if N is n
157d0 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61  egative, . ^If a
157e0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
157f0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
15800 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
15810 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
15820 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a   by the initial.
15830 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ** allocation, t
15840 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20  hen SQLite goes 
15850 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
15860 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79  oc()] separately
15870 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64   for each.** add
15880 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69  itional cache li
15890 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ne. </dd>.**.** 
158a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
158b0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
158c0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
158d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
158e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
158f0 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
15900 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
15910 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
15920 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
15930 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
15940 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
15950 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
15960 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
15970 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
15980 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
15990 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
159a0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
159b0 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
159c0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
159d0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
159e0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
159f0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
15a00 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
15a10 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
15a20 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
15a30 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
15a40 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
15a50 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
15a60 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
15a70 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
15a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15a90 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
15aa0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
15ab0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
15ac0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
15ad0 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
15ae0 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
15af0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
15b00 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
15b10 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
15b20 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
15b30 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
15b40 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
15b50 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
15b60 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
15b70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
15b80 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
15b90 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
15ba0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
15bb0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
15bc0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
15bd0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
15be0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
15bf0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
15c00 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
15c10 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
15c20 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
15c30 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
15c40 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
15c50 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
15c60 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
15c70 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
15c80 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
15c90 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
15ca0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
15cb0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
15cc0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
15cd0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
15ce0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
15cf0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
15d00 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
15d10 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
15d20 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
15d30 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
15d40 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
15d50 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
15d60 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
15d70 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
15d80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15d90 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
15da0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
15db0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15dc0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15dd0 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
15de0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15df0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
15e00 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15e10 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
15e20 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15e30 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15e40 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
15e50 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
15e60 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
15e70 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
15e80 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
15e90 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
15ea0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
15eb0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
15ec0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
15ed0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
15ee0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
15ef0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15f00 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15f10 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
15f20 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
15f30 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
15f40 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
15f50 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15f60 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15f70 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15f80 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15f90 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
15fa0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
15fb0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
15fc0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
15fd0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
15fe0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
15ff0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
16000 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
16010 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
16020 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
16030 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16040 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
16050 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
16060 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16070 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16080 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
16090 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
160a0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
160b0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
160c0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
160d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
160e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
160f0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
16100 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
16110 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
16120 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
16130 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
16140 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
16150 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
16160 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
16170 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
16180 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
16190 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
161a0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
161b0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
161c0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
161d0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
161e0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
161f0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
16200 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
16210 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
16220 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
16230 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
16240 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
16250 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
16260 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
16270 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
16280 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
16290 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
162a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
162b0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
162c0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
162d0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
162e0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
162f0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
16300 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
16310 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
16320 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16330 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
16340 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
16350 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
16360 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
16370 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16380 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16390 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
163a0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
163b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
163c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
163d0 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
163e0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
163f0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
16400 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
16410 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
16420 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
16430 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
16440 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
16450 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16460 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
16470 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
16480 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
16490 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
164a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
164b0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
164c0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
164d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
164e0 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
164f0 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
16500 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
16510 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
16520 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
16530 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16540 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
16550 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
16560 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
16570 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
16580 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
16590 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
165a0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
165b0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
165c0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
165d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
165e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
165f0 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
16600 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
16610 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16620 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
16630 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16640 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
16650 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16660 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
16670 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
16680 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
16690 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
166a0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
166b0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
166c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
166d0 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
166e0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
166f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
16700 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16710 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
16720 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16730 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
16740 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
16750 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
16760 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
16770 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16780 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
16790 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
167a0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
167b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
167c0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
167d0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
167e0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
167f0 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
16800 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
16810 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
16820 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
16830 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
16840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16850 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
16860 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
16870 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
16880 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
16890 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
168a0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
168b0 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
168c0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
168d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
168e0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
168f0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
16900 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
16910 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
16920 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
16930 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
16940 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
16950 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
16960 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
16970 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
16980 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
16990 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
169a0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
169b0 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
169c0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
169d0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
169e0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
169f0 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
16a00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
16a10 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
16a20 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
16a30 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
16a40 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
16a50 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
16a60 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
16a70 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
16a80 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
16a90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16aa0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
16ab0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
16ac0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
16ad0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
16ae0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
16af0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
16b00 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
16b10 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
16b20 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
16b30 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16b40 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
16b50 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
16b60 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
16b70 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
16b80 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
16b90 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
16ba0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
16bb0 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
16bc0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
16bd0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
16be0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
16bf0 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
16c00 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
16c10 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
16c20 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
16c30 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
16c40 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
16c50 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
16c60 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
16c70 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
16c80 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
16c90 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
16ca0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
16cb0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
16cc0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
16cd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
16ce0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
16cf0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
16d00 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
16d10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16d20 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
16d30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16d40 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
16d50 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16d60 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
16d70 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16d80 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
16d90 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
16da0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
16db0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
16dc0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
16dd0 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
16de0 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
16df0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16e00 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
16e10 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
16e20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
16e30 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
16e40 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
16e50 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
16e60 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
16e70 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
16e80 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
16e90 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
16ea0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
16eb0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
16ec0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
16ed0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
16ee0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
16ef0 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
16f00 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
16f10 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
16f20 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
16f30 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
16f40 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
16f50 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
16f60 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
16f70 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
16f80 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
16f90 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
16fa0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
16fb0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
16fc0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
16fd0 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
16fe0 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
16ff0 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
17000 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
17010 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
17020 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
17030 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
17040 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
17050 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
17060 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
17070 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
17080 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
17090 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
170a0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
170b0 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
170c0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
170d0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
170e0 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
170f0 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
17100 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
17110 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
17120 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
17130 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
17140 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
17150 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
17160 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
17170 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
17180 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
17190 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
171a0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
171b0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
171c0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
171d0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
171e0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
171f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17200 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
17210 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
17220 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
17230 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
17240 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
17250 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
17260 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
17270 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
17280 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
17290 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
172a0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
172b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
172c0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
172d0 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
172e0 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
172f0 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
17300 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
17310 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
17320 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
17330 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
17340 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
17350 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
17360 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
17370 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
17380 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
17390 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
173a0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
173b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
173c0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
173d0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
173e0 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
173f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
17400 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
17410 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
17420 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
17430 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
17440 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
17450 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
17460 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
17470 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
17480 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
17490 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
174a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
174b0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
174c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
174d0 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
174e0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
174f0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
17500 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
17510 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
17520 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
17530 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
17540 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
17550 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
17560 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
17570 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
17580 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
17590 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
175a0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
175b0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
175c0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
175d0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
175e0 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
175f0 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
17600 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
17610 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
17620 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
17630 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
17640 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
17650 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
17660 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
17670 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
17680 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
17690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
176a0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
176b0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
176c0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
176d0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
176e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
176f0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
17700 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
17710 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
17720 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
17730 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
17740 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
17750 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
17760 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
17770 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
17780 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
17790 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
177a0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
177b0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
177c0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
177d0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
177e0 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
177f0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
17800 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
17810 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
17820 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
17830 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
17840 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
17850 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
17860 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
17870 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
17880 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
17890 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
178a0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
178b0 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
178c0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
178d0 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
178e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
178f0 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
17900 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17910 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
17920 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
17930 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
17940 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
17950 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
17960 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
17970 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
17980 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
17990 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
179a0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
179b0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
179c0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
179d0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
179e0 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
179f0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
17a00 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
17a10 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
17a20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17a30 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
17a40 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
17a50 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
17a60 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
17a70 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
17a80 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
17a90 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
17aa0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
17ab0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
17ac0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
17ad0 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
17ae0 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
17af0 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
17b00 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
17b10 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
17b20 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
17b30 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
17b40 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
17b50 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
17b60 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
17b70 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
17b80 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
17b90 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
17ba0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
17bb0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
17bc0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
17bd0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
17be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17bf0 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
17c00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17c10 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17c20 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17c30 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17c40 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
17c50 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
17c60 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
17c70 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
17c80 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
17c90 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
17ca0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
17cb0 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
17cc0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
17cd0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
17ce0 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
17cf0 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
17d00 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
17d10 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
17d20 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
17d30 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
17d40 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
17d50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
17d60 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
17d70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17d80 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
17d90 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17da0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
17db0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17dc0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
17dd0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
17de0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17df0 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
17e00 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
17e10 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
17e20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
17e30 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
17e40 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
17e50 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
17e60 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
17e70 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
17e80 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
17e90 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
17ea0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
17eb0 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
17ec0 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
17ed0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
17ee0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17ef0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
17f00 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17f10 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
17f20 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17f30 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
17f40 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17f50 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
17f60 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
17f70 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
17f80 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
17f90 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
17fa0 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
17fb0 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
17fc0 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
17fd0 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
17fe0 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
17ff0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
18000 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
18010 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
18020 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
18030 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
18040 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
18050 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
18060 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
18070 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
18080 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
18090 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
180a0 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
180b0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
180c0 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
180d0 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
180e0 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
180f0 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
18100 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
18110 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
18120 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
18130 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  lue..**.** [[SQL
18140 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
18150 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c  RNL_SPILL]].** <
18160 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
18170 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a  _STMTJRNL_SPILL.
18180 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
18190 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
181a0 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20  NL_SPILL option 
181b0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
181c0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
181d0 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73  * becomes the [s
181e0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
181f0 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20  ] spill-to-disk 
18200 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20  threshold.  .** 
18210 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [Statement journ
18220 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e  als] are held in
18230 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68   memory until th
18240 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74  eir size (in byt
18250 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74  es).** exceeds t
18260 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61  his threshold, a
18270 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68  t which point th
18280 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74  ey are written t
18290 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66  o disk..** Or if
182a0 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69   the threshold i
182b0 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20  s -1, statement 
182c0 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77  journals are alw
182d0 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c  ays held.** excl
182e0 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72  usively in memor
182f0 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79  y..** Since many
18300 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
18310 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65  als never become
18320 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20   large, setting 
18330 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72  the spill.** thr
18340 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75  eshold to a valu
18350 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20  e such as 64KiB 
18360 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75  can greatly redu
18370 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ce the amount of
18380 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64  .** I/O required
18390 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74   to support stat
183a0 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a  ement rollback..
183b0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
183c0 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65  alue for this se
183d0 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c  tting is control
183e0 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  led by the.** [S
183f0 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53  QLITE_STMTJRNL_S
18400 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  PILL] compile-ti
18410 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  me option..**.**
18420 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
18430 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 5d  _SORTERREF_SIZE]
18440 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
18450 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46  CONFIG_SORTERREF
18460 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65  _SIZE.** <dd>The
18470 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18480 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f 70  ORTERREF_SIZE op
18490 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73  tion accepts a s
184a0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a  ingle parameter.
184b0 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74 29  ** of type (int)
184c0 20 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75 65   - the new value
184d0 20 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d 72   of the sorter-r
184e0 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68  eference size th
184f0 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75 61  reshold..** Usua
18500 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74 65  lly, when SQLite
18510 20 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e 61   uses an externa
18520 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72 20  l sort to order 
18530 72 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69 6e  records accordin
18540 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45 52  g.** to an ORDER
18550 20 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c 20   BY clause, all 
18560 66 69 65 6c 64 73 20 72 65 71 75 69 72 65 64 20  fields required 
18570 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61 72  by the caller ar
18580 65 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65  e present in the
18590 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f 72  .** sorted recor
185a0 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20  ds. However, if 
185b0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
185c0 73 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 64  s based on the d
185d0 65 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a 20  eclared type.** 
185e0 6f 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  of a table colum
185f0 6e 20 74 68 61 74 20 69 74 73 20 76 61 6c 75 65  n that its value
18600 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
18610 62 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d 20  be very large - 
18620 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20 74  larger.** than t
18630 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73 6f  he configured so
18640 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73  rter-reference s
18650 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d 20  ize threshold - 
18660 74 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63 65  then a reference
18670 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69 6e  .** is stored in
18680 20 65 61 63 68 20 73 6f 72 74 65 64 20 72 65 63   each sorted rec
18690 6f 72 64 20 61 6e 64 20 74 68 65 20 72 65 71 75  ord and the requ
186a0 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ired column valu
186b0 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72 6f  es loaded.** fro
186c0 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  m the database a
186d0 73 20 72 65 63 6f 72 64 73 20 61 72 65 20 72 65  s records are re
186e0 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65 64  turned in sorted
186f0 20 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66 61   order. The defa
18700 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72  ult.** value for
18710 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
18720 74 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68 69  to never use thi
18730 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20  s optimization. 
18740 53 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a 2a  Specifying a .**
18750 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
18760 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  for this option 
18770 72 65 73 74 6f 72 65 73 20 74 68 65 20 64 65 66  restores the def
18780 61 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e 0a  ault behaviour..
18790 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  ** This option i
187a0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
187b0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
187c0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
187d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
187e0 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45 4e  E_SORTER_REFEREN
187f0 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CES] compile-tim
18800 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  e option..**.** 
18810 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
18820 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 5d 5d 0a  MEMDB_MAXSIZE]].
18830 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
18840 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49  NFIG_MEMDB_MAXSI
18850 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  ZE.** <dd>The SQ
18860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44  LITE_CONFIG_MEMD
18870 42 5f 4d 41 58 53 49 5a 45 20 6f 70 74 69 6f 6e  B_MAXSIZE option
18880 20 61 63 63 65 70 74 73 20 61 20 73 69 6e 67 6c   accepts a singl
18890 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 5b  e parameter.** [
188a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 70  sqlite3_int64] p
188b0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 20 69  arameter which i
188c0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61  s the default ma
188d0 78 69 6d 75 6d 20 73 69 7a 65 20 66 6f 72 20 61  ximum size for a
188e0 6e 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64  n in-memory.** d
188f0 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20  atabase created 
18900 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 64  using [sqlite3_d
18910 65 73 65 72 69 61 6c 69 7a 65 28 29 5d 2e 20 20  eserialize()].  
18920 54 68 69 73 20 64 65 66 61 75 6c 74 20 6d 61 78  This default max
18930 69 6d 75 6d 0a 2a 2a 20 73 69 7a 65 20 63 61 6e  imum.** size can
18940 20 62 65 20 61 64 6a 75 73 74 65 64 20 75 70 20   be adjusted up 
18950 6f 72 20 64 6f 77 6e 20 66 6f 72 20 69 6e 64 69  or down for indi
18960 76 69 64 75 61 6c 20 64 61 74 61 62 61 73 65 73  vidual databases
18970 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
18980 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
18990 5f 4c 49 4d 49 54 5d 20 5b 73 71 6c 69 74 65 33  _LIMIT] [sqlite3
189a0 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 7c 66 69  _file_control|fi
189b0 6c 65 2d 63 6f 6e 74 72 6f 6c 5d 2e 20 20 49 66  le-control].  If
189c0 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
189d0 72 61 74 69 6f 6e 20 73 65 74 74 69 6e 67 20 69  ration setting i
189e0 73 20 6e 65 76 65 72 20 75 73 65 64 2c 20 74 68  s never used, th
189f0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  en the default m
18a00 61 78 69 6d 75 6d 20 69 73 20 64 65 74 65 72 6d  aximum is determ
18a10 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
18a20 53 51 4c 49 54 45 5f 4d 45 4d 44 42 5f 44 45 46  SQLITE_MEMDB_DEF
18a30 41 55 4c 54 5f 4d 41 58 53 49 5a 45 5d 20 63 6f  AULT_MAXSIZE] co
18a40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
18a50 6e 2e 20 20 49 66 20 74 68 61 74 0a 2a 2a 20 63  n.  If that.** c
18a60 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
18a70 6f 6e 20 69 73 20 6e 6f 74 20 73 65 74 2c 20 74  on is not set, t
18a80 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
18a90 6d 61 78 69 6d 75 6d 20 69 73 20 31 30 37 33 37  maximum is 10737
18aa0 34 31 38 32 34 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  41824..** </dl>.
18ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ac0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
18ad0 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
18ae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18af0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
18b00 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
18b10 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
18b20 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
18b30 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
18b40 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
18b50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
18b60 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
18b70 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
18b80 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
18b90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
18ba0 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
18bb0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
18bc0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
18bd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18be0 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
18bf0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
18c00 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
18c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
18c20 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
18c30 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
18c40 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
18c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
18c60 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
18c70 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
18c80 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
18c90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18ca0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
18cb0 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
18cc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18cd0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
18ce0 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
18cf0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
18d00 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
18d10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
18d20 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
18d30 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
18d40 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
18d50 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
18d60 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
18d70 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
18d80 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
18d90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18da0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
18db0 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
18dc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18dd0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
18de0 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
18df0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
18e00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18e10 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
18e20 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
18e30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18e40 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
18e50 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
18e60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e70 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
18e80 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
18e90 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
18ea0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
18eb0 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
18ec0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
18ed0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
18ee0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18ef0 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
18f00 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
18f10 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
18f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18f30 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
18f40 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
18f50 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
18f60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18f70 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
18f80 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
18f90 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18fa0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
18fb0 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
18fc0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
18fd0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
18fe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18ff0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
19000 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
19010 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
19020 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19030 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
19040 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
19050 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
19060 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19070 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
19080 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
19090 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
190a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
190b0 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
190c0 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f  SPILL      26  /
190d0 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
190e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
190f0 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f  NFIG_SMALL_MALLO
19100 43 20 20 20 20 20 20 20 20 32 37 20 20 2f 2a 20  C        27  /* 
19110 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
19120 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
19130 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20  _SORTERREF_SIZE 
19140 20 20 20 20 20 32 38 20 20 2f 2a 20 69 6e 74 20       28  /* int 
19150 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
19160 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
19170 45 4d 44 42 5f 4d 41 58 53 49 5a 45 20 20 20 20  EMDB_MAXSIZE    
19180 20 20 20 32 39 20 20 2f 2a 20 73 71 6c 69 74 65     29  /* sqlite
19190 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a  3_int64 */../*.*
191a0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
191b0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
191c0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
191d0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
191e0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
191f0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
19200 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
19210 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
19220 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
19230 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
19240 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
19250 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
19260 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
19270 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
19280 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
19290 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
192a0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
192b0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
192c0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
192d0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
192e0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
192f0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
19300 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
19310 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
19320 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
19330 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
19340 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
19350 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
19360 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
19370 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
19380 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
19390 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
193a0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
193b0 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
193c0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
193d0 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
193e0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
193f0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
19400 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
19410 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
19420 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
19430 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
19440 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
19450 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
19460 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
19470 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
19480 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
19490 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
194a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
194b0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
194c0 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
194d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
194e0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
194f0 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
19500 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
19510 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
19520 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
19530 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
19540 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
19550 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
19560 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
19570 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
19580 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
19590 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
195a0 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
195b0 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
195c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
195d0 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
195e0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
195f0 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
19600 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
19610 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
19620 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
19630 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
19640 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
19650 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
19660 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
19670 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
19680 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
19690 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
196a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
196b0 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
196c0 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
196d0 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
196e0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
196f0 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
19700 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
19710 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
19720 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
19730 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
19740 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
19750 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
19760 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
19770 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
19780 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
19790 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
197a0 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
197b0 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
197c0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
197d0 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
197e0 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
197f0 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
19800 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19810 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
19820 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
19830 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
19840 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
19850 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
19860 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
19870 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
19880 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
19890 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
198a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
198b0 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
198c0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
198d0 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
198e0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
198f0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
19900 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
19910 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
19920 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
19930 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
19940 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
19950 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
19960 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
19970 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
19980 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
19990 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
199a0 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 5d 5d 0a 2a  _ENABLE_FKEY]].*
199b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
199c0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
199d0 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
199e0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
199f0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
19a00 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
19a10 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
19a20 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
19a30 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
19a40 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
19a50 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
19a60 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
19a70 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
19a80 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
19a90 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
19aa0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
19ab0 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
19ac0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
19ad0 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
19ae0 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
19af0 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
19b00 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
19b10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
19b20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
19b30 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
19b40 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
19b50 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
19b60 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
19b70 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
19b80 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
19b90 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
19ba0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19bb0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
19bc0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
19bd0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
19be0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
19bf0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
19c00 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
19c10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
19c20 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19c30 4c 45 5f 54 52 49 47 47 45 52 5d 5d 0a 2a 2a 20  LE_TRIGGER]].** 
19c40 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
19c50 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
19c60 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
19c70 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
19c80 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
19c90 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
19ca0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
19cb0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
19cc0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
19cd0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
19ce0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
19cf0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
19d00 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
19d10 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
19d20 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
19d30 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
19d40 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
19d50 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
19d60 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
19d70 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
19d80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19d90 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19da0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19db0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19dc0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19dd0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
19de0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
19df0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
19e00 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19e10 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19e20 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
19e30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
19e40 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
19e50 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
19e60 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
19e70 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
19e80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
19e90 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19ea0 56 49 45 57 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  VIEW]].** <dt>SQ
19eb0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19ec0 41 42 4c 45 5f 56 49 45 57 3c 2f 64 74 3e 0a 2a  ABLE_VIEW</dt>.*
19ed0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
19ee0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
19ef0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
19f00 20 5b 43 52 45 41 54 45 20 56 49 45 57 20 7c 20   [CREATE VIEW | 
19f10 76 69 65 77 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  views]..** There
19f20 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
19f30 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
19f40 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
19f50 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
19f60 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
19f70 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 76  s 0 to disable v
19f80 69 65 77 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  iews,.** positiv
19f90 65 20 74 6f 20 65 6e 61 62 6c 65 20 76 69 65 77  e to enable view
19fa0 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
19fb0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
19fc0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
19fd0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
19fe0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
19ff0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
1a000 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
1a010 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
1a020 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
1a030 74 68 65 72 20 76 69 65 77 73 20 61 72 65 20 64  ther views are d
1a040 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
1a050 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
1a060 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
1a070 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a080 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
1a090 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
1a0a0 69 63 68 20 63 61 73 65 20 74 68 65 20 76 69 65  ich case the vie
1a0b0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
1a0c0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
1a0d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
1a0e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1a0f0 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
1a100 5a 45 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  ZER]].** <dt>SQL
1a110 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1a120 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
1a130 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
1a140 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
1a150 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
1a160 72 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a  r disable the.**
1a170 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72   [fts3_tokenizer
1a180 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69  ()] function whi
1a190 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ch is part of th
1a1a0 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c  e.** [FTS3] full
1a1b0 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67  -text search eng
1a1c0 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a  ine extension..*
1a1d0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
1a1e0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
1a1f0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
1a200 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1a210 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
1a220 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
1a230 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  sable fts3_token
1a240 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73  izer() or.** pos
1a250 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
1a260 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
1a270 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
1a280 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
1a290 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a  g.** unchanged..
1a2a0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
1a2b0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1a2c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
1a2d0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
1a2e0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
1a2f0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
1a300 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65  hether fts3_toke
1a310 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  nizer is disable
1a320 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
1a330 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
1a340 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
1a350 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
1a360 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
1a370 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
1a380 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
1a390 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
1a3a0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
1a3b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42  *.** [[SQLITE_DB
1a3c0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f  CONFIG_ENABLE_LO
1a3d0 41 44 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d 0a 2a  AD_EXTENSION]].*
1a3e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
1a3f0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
1a400 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e  D_EXTENSION</dt>
1a410 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
1a420 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
1a430 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
1a440 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
1a450 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1a460 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ].** interface i
1a470 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20  ndependently of 
1a480 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73  the [load_extens
1a490 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  ion()] SQL funct
1a4a0 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ion..** The [sql
1a4b0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
1a4c0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50  _extension()] AP
1a4d0 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  I enables or dis
1a4e0 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a  ables both the.*
1a4f0 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33  * C-API [sqlite3
1a500 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
1a510 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  )] and the SQL f
1a520 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78  unction [load_ex
1a530 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54  tension()]..** T
1a540 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
1a550 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
1a560 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e  guments..** When
1a570 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1a580 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65  ent to this inte
1a590 72 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e  rface is 1, then
1a5a0 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20   only the C-API 
1a5b0 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e  is.** enabled an
1a5c0 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
1a5d0 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62  on remains disab
1a5e0 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72  led.  If the fir
1a5f0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  st argument to.*
1a600 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  * this interface
1a610 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68   is 0, then both
1a620 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74   the C-API and t
1a630 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
1a640 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  are disabled..**
1a650 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72   If the first ar
1a660 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68  gument is -1, th
1a670 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72  en no changes ar
1a680 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20  e made to state 
1a690 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a  of either the.**
1a6a0 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51   C-API or the SQ
1a6b0 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  L function..** T
1a6c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a6d0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
1a6e0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
1a6f0 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
1a700 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
1a710 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
1a720 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  er [sqlite3_load
1a730 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e  _extension()] in
1a740 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69  terface.** is di
1a750 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
1a760 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  d following this
1a770 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
1a780 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
1a790 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  .** be a NULL po
1a7a0 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20  inter, in which 
1a7b0 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
1a7c0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
1a7d0 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f  rted back..** </
1a7e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
1a7f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
1a800 44 42 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53 51 4c  DBNAME]] <dt>SQL
1a810 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
1a820 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20  NDBNAME</dt>.** 
1a830 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
1a840 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61  n is used to cha
1a850 6e 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nge the name of 
1a860 74 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62  the "main" datab
1a870 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20  ase.** schema.  
1a880 5e 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65  ^The sole argume
1a890 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
1a8a0 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54  to a constant UT
1a8b0 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69  F8 string.** whi
1a8c0 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ch will become t
1a8d0 68 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61  he new schema na
1a8e0 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22  me in place of "
1a8f0 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a  main".  ^SQLite.
1a900 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65  ** does not make
1a910 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e   a copy of the n
1a920 65 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e  ew main schema n
1a930 61 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74  ame string, so t
1a940 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
1a950 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  * must ensure th
1a960 61 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  at the argument 
1a970 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73  passed into this
1a980 20 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e   DBCONFIG option
1a990 20 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a   is unchanged.**
1a9a0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
1a9b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a9c0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20  tion closes..** 
1a9d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
1a9e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
1a9f0 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 5d 5d  _CKPT_ON_CLOSE]]
1aa00 20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f   .** <dt>SQLITE_
1aa10 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54  DBCONFIG_NO_CKPT
1aa20 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a  _ON_CLOSE</dt>.*
1aa30 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20  * <dd> Usually, 
1aa40 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1aa50 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63  in wal mode is c
1aa60 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65  losed or detache
1aa70 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74  d from a .** dat
1aa80 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51  abase handle, SQ
1aa90 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74  Lite checks if t
1aaa0 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68  his will mean th
1aab0 61 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77  at there are now
1aac0 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69   no .** connecti
1aad0 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68  ons at all to th
1aae0 65 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73  e database. If s
1aaf0 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61  o, it performs a
1ab00 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20   checkpoint .** 
1ab10 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65  operation before
1ab20 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e   closing the con
1ab30 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70  nection. This op
1ab40 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64  tion may be used
1ab50 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20   to.** override 
1ab60 74 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20  this behaviour. 
1ab70 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1ab80 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
1ab90 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  is operation.** 
1aba0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20  is an integer - 
1abb0 70 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61  positive to disa
1abc0 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  ble checkpoints-
1abd0 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72  on-close, or zer
1abe0 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  o (the.** defaul
1abf0 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65  t) to enable the
1ac00 6d 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20  m, and negative 
1ac10 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
1ac20 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
1ac30 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
1ac40 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1ac50 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
1ac60 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68  er.** into which
1ac70 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
1ac80 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
1ac90 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e  hether checkpoin
1aca0 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68  ts-on-close.** h
1acb0 61 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65  ave been disable
1acc0 64 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72  d - 0 if they ar
1acd0 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20  e not disabled, 
1ace0 31 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a  1 if they are..*
1acf0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
1ad00 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1ad10 45 4e 41 42 4c 45 5f 51 50 53 47 5d 5d 20 3c 64  ENABLE_QPSG]] <d
1ad20 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1ad30 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64  G_ENABLE_QPSG</d
1ad40 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20  t>.** <dd>^(The 
1ad50 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1ad60 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69  ENABLE_QPSG opti
1ad70 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20  on activates or 
1ad80 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74  deactivates.** t
1ad90 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65  he [query planne
1ada0 72 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72  r stability guar
1adb0 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20  antee] (QPSG).  
1adc0 57 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73  When the QPSG is
1add0 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69   active,.** a si
1ade0 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73  ngle SQL query s
1adf0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c  tatement will al
1ae00 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d  ways use the sam
1ae10 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61  e algorithm rega
1ae20 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c  rdless.** of val
1ae30 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  ues of [bound pa
1ae40 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65  rameters].)^ The
1ae50 20 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73   QPSG disables s
1ae60 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  ome query optimi
1ae70 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  zations.** that 
1ae80 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75  look at the valu
1ae90 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61  es of bound para
1aea0 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61  meters, which ca
1aeb0 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72  n make some quer
1aec0 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20  ies.** slower.  
1aed0 42 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73  But the QPSG has
1aee0 20 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f   the advantage o
1aef0 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62  f more predictab
1af00 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69  le behavior.  Wi
1af10 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61  th.** the QPSG a
1af20 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69  ctive, SQLite wi
1af30 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68  ll always use th
1af40 65 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61  e same query pla
1af50 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61  n in the field a
1af60 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75  s.** was used du
1af70 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20  ring testing in 
1af80 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20  the lab..** The 
1af90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1afa0 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  o this setting i
1afb0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
1afc0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
1afd0 6c 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c  le .** the QPSG,
1afe0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
1aff0 62 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67  ble QPSG, or neg
1b000 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
1b010 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e  he setting.** un
1b020 63 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63  changed. The sec
1b030 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1b040 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
1b050 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
1b060 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
1b070 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
1b080 63 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65  cate whether the
1b090 20 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65   QPSG is disable
1b0a0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
1b0b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
1b0c0 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  all..** </dd>.**
1b0d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
1b0e0 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51  ONFIG_TRIGGER_EQ
1b0f0 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  P]] <dt>SQLITE_D
1b100 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f  BCONFIG_TRIGGER_
1b110 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EQP</dt>.** <dd>
1b120 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
1b130 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41   output of EXPLA
1b140 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f  IN QUERY PLAN co
1b150 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20  mmands does not 
1b160 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70  .** include outp
1b170 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61  ut for any opera
1b180 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20  tions performed 
1b190 62 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  by trigger progr
1b1a0 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74  ams. This.** opt
1b1b0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73  ion is used to s
1b1c0 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65  et or clear (the
1b1d0 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67   default) a flag
1b1e0 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68   that governs th
1b1f0 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20  is.** behavior. 
1b200 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1b210 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
1b220 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  is operation is 
1b230 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20  an integer -.** 
1b240 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
1b250 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72  le output for tr
1b260 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20  igger programs, 
1b270 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  or zero to disab
1b280 6c 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67  le it,.** or neg
1b290 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
1b2a0 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
1b2b0 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
1b2c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1b2d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
1b2e0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
1b2f0 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a  ich is written .
1b300 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  ** 0 or 1 to ind
1b310 69 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75  icate whether ou
1b320 74 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72  tput-for-trigger
1b330 73 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62  s has been disab
1b340 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69  led - 0 if .** i
1b350 74 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65  t is not disable
1b360 64 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20  d, 1 if it is.  
1b370 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1b380 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
1b390 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45  G_RESET_DATABASE
1b3a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ]] <dt>SQLITE_DB
1b3b0 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1b3c0 41 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ABASE</dt>.** <d
1b3d0 64 3e 20 53 65 74 20 74 68 65 20 53 51 4c 49 54  d> Set the SQLIT
1b3e0 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54  E_DBCONFIG_RESET
1b3f0 5f 44 41 54 41 42 41 53 45 20 66 6c 61 67 20 61  _DATABASE flag a
1b400 6e 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b  nd then run.** [
1b410 56 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72  VACUUM] in order
1b420 20 74 6f 20 72 65 73 65 74 20 61 20 64 61 74 61   to reset a data
1b430 62 61 73 65 20 62 61 63 6b 20 74 6f 20 61 6e 20  base back to an 
1b440 65 6d 70 74 79 20 64 61 74 61 62 61 73 65 0a 2a  empty database.*
1b450 2a 20 77 69 74 68 20 6e 6f 20 73 63 68 65 6d 61  * with no schema
1b460 20 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e   and no content.
1b470 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   The following p
1b480 72 6f 63 65 73 73 20 77 6f 72 6b 73 20 65 76 65  rocess works eve
1b490 6e 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79  n for.** a badly
1b4a0 20 63 6f 72 72 75 70 74 65 64 20 64 61 74 61 62   corrupted datab
1b4b0 61 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c  ase file:.** <ol
1b4c0 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74 68 65  >.** <li> If the
1b4d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b4e0 74 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20 6f 70  tion is newly op
1b4f0 65 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72 65 20  ened, make sure 
1b500 69 74 20 68 61 73 20 72 65 61 64 20 74 68 65 0a  it has read the.
1b510 2a 2a 20 20 20 20 20 20 64 61 74 61 62 61 73 65  **      database
1b520 20 73 63 68 65 6d 61 20 62 79 20 70 72 65 70 61   schema by prepa
1b530 72 69 6e 67 20 74 68 65 6e 20 64 69 73 63 61 72  ring then discar
1b540 64 69 6e 67 20 73 6f 6d 65 20 71 75 65 72 79 20  ding some query 
1b550 61 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a 20 20  against the.**  
1b560 20 20 20 20 64 61 74 61 62 61 73 65 2c 20 6f 72      database, or
1b570 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
1b580 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65  _table_column_me
1b590 74 61 64 61 74 61 28 29 2c 20 69 67 6e 6f 72 69  tadata(), ignori
1b5a0 6e 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 65  ng any.**      e
1b5b0 72 72 6f 72 73 2e 20 20 54 68 69 73 20 73 74 65  rrors.  This ste
1b5c0 70 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65 73 73  p is only necess
1b5d0 61 72 79 20 69 66 20 74 68 65 20 61 70 70 6c 69  ary if the appli
1b5e0 63 61 74 69 6f 6e 20 64 65 73 69 72 65 73 20 74  cation desires t
1b5f0 6f 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20 20 74  o keep.**      t
1b600 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 20 57  he database in W
1b610 41 4c 20 6d 6f 64 65 20 61 66 74 65 72 20 74 68  AL mode after th
1b620 65 20 72 65 73 65 74 20 69 66 20 69 74 20 77 61  e reset if it wa
1b630 73 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20 62 65  s in WAL mode be
1b640 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74 68 65  fore.**      the
1b650 20 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c 6c 69   reset.  .** <li
1b660 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  > sqlite3_db_con
1b670 66 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44  fig(db, SQLITE_D
1b680 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41  BCONFIG_RESET_DA
1b690 54 41 42 41 53 45 2c 20 31 2c 20 30 29 3b 0a 2a  TABASE, 1, 0);.*
1b6a0 2a 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f  * <li> [sqlite3_
1b6b0 65 78 65 63 5d 28 64 62 2c 20 22 5b 56 41 43 55  exec](db, "[VACU
1b6c0 55 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  UM]", 0, 0, 0);.
1b6d0 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f  ** <li> sqlite3_
1b6e0 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51  db_config(db, SQ
1b6f0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45  LITE_DBCONFIG_RE
1b700 53 45 54 5f 44 41 54 41 42 41 53 45 2c 20 30 2c  SET_DATABASE, 0,
1b710 20 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a   0);.** </ol>.**
1b720 20 42 65 63 61 75 73 65 20 72 65 73 65 74 74 69   Because resetti
1b730 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 69 73  ng a database is
1b740 20 64 65 73 74 72 75 63 74 69 76 65 20 61 6e 64   destructive and
1b750 20 69 72 72 65 76 65 72 73 69 62 6c 65 2c 20 74   irreversible, t
1b760 68 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20 72 65  he.** process re
1b770 71 75 69 72 65 73 20 74 68 65 20 75 73 65 20 6f  quires the use o
1b780 66 20 74 68 69 73 20 6f 62 73 63 75 72 65 20 41  f this obscure A
1b790 50 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c 65 20  PI and multiple 
1b7a0 73 74 65 70 73 20 74 6f 20 68 65 6c 70 0a 2a 2a  steps to help.**
1b7b0 20 65 6e 73 75 72 65 20 74 68 61 74 20 69 74 20   ensure that it 
1b7c0 64 6f 65 73 20 6e 6f 74 20 68 61 70 70 65 6e 20  does not happen 
1b7d0 62 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a 2a 0a  by accident..**.
1b7e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
1b7f0 4e 46 49 47 5f 44 45 46 45 4e 53 49 56 45 5d 5d  NFIG_DEFENSIVE]]
1b800 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
1b810 4e 46 49 47 5f 44 45 46 45 4e 53 49 56 45 3c 2f  NFIG_DEFENSIVE</
1b820 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53  dt>.** <dd>The S
1b830 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44  QLITE_DBCONFIG_D
1b840 45 46 45 4e 53 49 56 45 20 6f 70 74 69 6f 6e 20  EFENSIVE option 
1b850 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61  activates or dea
1b860 63 74 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20  ctivates the.** 
1b870 22 64 65 66 65 6e 73 69 76 65 22 20 66 6c 61 67  "defensive" flag
1b880 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
1b890 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 57 68 65  connection.  Whe
1b8a0 6e 20 74 68 65 20 64 65 66 65 6e 73 69 76 65 0a  n the defensive.
1b8b0 2a 2a 20 66 6c 61 67 20 69 73 20 65 6e 61 62 6c  ** flag is enabl
1b8c0 65 64 2c 20 6c 61 6e 67 75 61 67 65 20 66 65 61  ed, language fea
1b8d0 74 75 72 65 73 20 74 68 61 74 20 61 6c 6c 6f 77  tures that allow
1b8e0 20 6f 72 64 69 6e 61 72 79 20 53 51 4c 20 74 6f   ordinary SQL to
1b8f0 20 0a 2a 2a 20 64 65 6c 69 62 65 72 61 74 65 6c   .** deliberatel
1b900 79 20 63 6f 72 72 75 70 74 20 74 68 65 20 64 61  y corrupt the da
1b910 74 61 62 61 73 65 20 66 69 6c 65 20 61 72 65 20  tabase file are 
1b920 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20 64  disabled.  The d
1b930 69 73 61 62 6c 65 64 0a 2a 2a 20 66 65 61 74 75  isabled.** featu
1b940 72 65 73 20 69 6e 63 6c 75 64 65 20 62 75 74 20  res include but 
1b950 61 72 65 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20  are not limited 
1b960 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  to the following
1b970 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
1b980 3e 20 54 68 65 20 5b 50 52 41 47 4d 41 20 77 72  > The [PRAGMA wr
1b990 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e  itable_schema=ON
1b9a0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
1b9b0 3c 6c 69 3e 20 54 68 65 20 5b 50 52 41 47 4d 41  <li> The [PRAGMA
1b9c0 20 6a 6f 75 72 6e 61 6c 5f 6d 6f 64 65 3d 4f 46   journal_mode=OF
1b9d0 46 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  F] statement..**
1b9e0 20 3c 6c 69 3e 20 57 72 69 74 65 73 20 74 6f 20   <li> Writes to 
1b9f0 74 68 65 20 5b 73 71 6c 69 74 65 5f 64 62 70 61  the [sqlite_dbpa
1ba00 67 65 5d 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ge] virtual tabl
1ba10 65 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 63  e..** <li> Direc
1ba20 74 20 77 72 69 74 65 73 20 74 6f 20 5b 73 68 61  t writes to [sha
1ba30 64 6f 77 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  dow tables]..** 
1ba40 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  </ul>.** </dd>.*
1ba50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42  *.** [[SQLITE_DB
1ba60 43 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f  CONFIG_WRITABLE_
1ba70 53 43 48 45 4d 41 5d 5d 20 3c 64 74 3e 53 51 4c  SCHEMA]] <dt>SQL
1ba80 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49  ITE_DBCONFIG_WRI
1ba90 54 41 42 4c 45 5f 53 43 48 45 4d 41 3c 2f 64 74  TABLE_SCHEMA</dt
1baa0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  >.** <dd>The SQL
1bab0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 57 52 49  ITE_DBCONFIG_WRI
1bac0 54 41 42 4c 45 5f 53 43 48 45 4d 41 20 6f 70 74  TABLE_SCHEMA opt
1bad0 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72  ion activates or
1bae0 20 64 65 61 63 74 69 76 61 74 65 73 20 74 68 65   deactivates the
1baf0 0a 2a 2a 20 22 77 72 69 74 61 62 6c 65 5f 73 63  .** "writable_sc
1bb00 68 65 6d 61 22 20 66 6c 61 67 2e 20 54 68 69 73  hema" flag. This
1bb10 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66   has the same ef
1bb20 66 65 63 74 20 61 6e 64 20 69 73 20 6c 6f 67 69  fect and is logi
1bb30 63 61 6c 6c 79 20 65 71 75 69 76 61 6c 65 6e 74  cally equivalent
1bb40 0a 2a 2a 20 74 6f 20 73 65 74 74 69 6e 67 20 5b  .** to setting [
1bb50 50 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f  PRAGMA writable_
1bb60 73 63 68 65 6d 61 3d 4f 4e 5d 20 6f 72 20 5b 50  schema=ON] or [P
1bb70 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65 5f 73  RAGMA writable_s
1bb80 63 68 65 6d 61 3d 4f 46 46 5d 2e 0a 2a 2a 20 54  chema=OFF]..** T
1bb90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1bba0 74 20 74 6f 20 74 68 69 73 20 73 65 74 74 69 6e  t to this settin
1bbb0 67 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  g is an integer 
1bbc0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
1bbd0 73 61 62 6c 65 20 0a 2a 2a 20 74 68 65 20 77 72  sable .** the wr
1bbe0 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20 70  itable_schema, p
1bbf0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1bc00 65 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d  e writable_schem
1bc10 61 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  a, or negative t
1bc20 6f 0a 2a 2a 20 6c 65 61 76 65 20 74 68 65 20 73  o.** leave the s
1bc30 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
1bc40 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
1bc50 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
1bc60 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 74  ter to an.** int
1bc70 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20  eger into which 
1bc80 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
1bc90 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
1bca0 65 74 68 65 72 20 74 68 65 20 77 72 69 74 61 62  ether the writab
1bcb0 6c 65 5f 73 63 68 65 6d 61 0a 2a 2a 20 69 73 20  le_schema.** is 
1bcc0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
1bcd0 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  led following th
1bce0 69 73 20 63 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64  is call..** </dd
1bcf0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
1bd00 5f 44 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59  _DBCONFIG_LEGACY
1bd10 5f 41 4c 54 45 52 5f 54 41 42 4c 45 5d 5d 0a 2a  _ALTER_TABLE]].*
1bd20 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
1bd30 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54  ONFIG_LEGACY_ALT
1bd40 45 52 5f 54 41 42 4c 45 3c 2f 64 74 3e 0a 2a 2a  ER_TABLE</dt>.**
1bd50 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f   <dd>The SQLITE_
1bd60 44 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f  DBCONFIG_LEGACY_
1bd70 41 4c 54 45 52 5f 54 41 42 4c 45 20 6f 70 74 69  ALTER_TABLE opti
1bd80 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20  on activates or 
1bd90 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74  deactivates.** t
1bda0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1bdb0 6f 72 20 6f 66 20 74 68 65 20 5b 41 4c 54 45 52  or of the [ALTER
1bdc0 20 54 41 42 4c 45 20 52 45 4e 41 4d 45 5d 20 63   TABLE RENAME] c
1bdd0 6f 6d 6d 61 6e 64 20 73 75 63 68 20 69 74 0a 2a  ommand such it.*
1bde0 2a 20 62 65 68 61 76 65 73 20 61 73 20 69 74 20  * behaves as it 
1bdf0 64 69 64 20 70 72 69 6f 72 20 74 6f 20 5b 76 65  did prior to [ve
1be00 72 73 69 6f 6e 20 33 2e 32 34 2e 30 5d 20 28 32  rsion 3.24.0] (2
1be10 30 31 38 2d 30 36 2d 30 34 29 2e 20 20 53 65 65  018-06-04).  See
1be20 20 74 68 65 0a 2a 2a 20 22 43 6f 6d 70 61 74 69   the.** "Compati
1be30 62 69 6c 69 74 79 20 4e 6f 74 69 63 65 22 20 6f  bility Notice" o
1be40 6e 20 74 68 65 20 5b 41 4c 54 45 52 20 54 41 42  n the [ALTER TAB
1be50 4c 45 20 52 45 4e 41 4d 45 20 64 6f 63 75 6d 65  LE RENAME docume
1be60 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20  ntation] for.** 
1be70 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
1be80 6d 61 74 69 6f 6e 2e 20 54 68 69 73 20 66 65 61  mation. This fea
1be90 74 75 72 65 20 63 61 6e 20 61 6c 73 6f 20 62 65  ture can also be
1bea0 20 74 75 72 6e 65 64 20 6f 6e 20 61 6e 64 20 6f   turned on and o
1beb0 66 66 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ff.** using the 
1bec0 5b 50 52 41 47 4d 41 20 6c 65 67 61 63 79 5f 61  [PRAGMA legacy_a
1bed0 6c 74 65 72 5f 74 61 62 6c 65 5d 20 73 74 61 74  lter_table] stat
1bee0 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  ement..** </dd>.
1bef0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  **.** [[SQLITE_D
1bf00 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 5d  BCONFIG_DQS_DML]
1bf10 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
1bf20 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 4d 4c  DBCONFIG_DQS_DML
1bf30 3c 2f 74 64 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </td>.** <dd>The
1bf40 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1bf50 5f 44 51 53 5f 44 4d 4c 20 6f 70 74 69 6f 6e 20  _DQS_DML option 
1bf60 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61  activates or dea
1bf70 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20  ctivates.** the 
1bf80 6c 65 67 61 63 79 20 5b 64 6f 75 62 6c 65 2d 71  legacy [double-q
1bf90 75 6f 74 65 64 20 73 74 72 69 6e 67 20 6c 69 74  uoted string lit
1bfa0 65 72 61 6c 5d 20 6d 69 73 66 65 61 74 75 72 65  eral] misfeature
1bfb0 20 66 6f 72 20 44 4d 4c 20 73 74 61 74 65 6d 65   for DML stateme
1bfc0 6e 74 0a 2a 2a 20 6f 6e 6c 79 2c 20 74 68 61 74  nt.** only, that
1bfd0 20 69 73 20 44 45 4c 45 54 45 2c 20 49 4e 53 45   is DELETE, INSE
1bfe0 52 54 2c 20 53 45 4c 45 43 54 2c 20 61 6e 64 20  RT, SELECT, and 
1bff0 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
1c000 73 2e 20 54 68 65 0a 2a 2a 20 64 65 66 61 75 6c  s. The.** defaul
1c010 74 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  t value of this 
1c020 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
1c030 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 2d 44  mined by the [-D
1c040 53 51 4c 49 54 45 5f 44 51 53 5d 0a 2a 2a 20 63  SQLITE_DQS].** c
1c050 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
1c060 6f 6e 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  on..** </dd>.**.
1c070 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
1c080 4e 46 49 47 5f 44 51 53 5f 44 44 4c 5d 5d 0a 2a  NFIG_DQS_DDL]].*
1c090 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
1c0a0 4f 4e 46 49 47 5f 44 51 53 5f 44 44 4c 3c 2f 74  ONFIG_DQS_DDL</t
1c0b0 64 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  d>.** <dd>The SQ
1c0c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 51  LITE_DBCONFIG_DQ
1c0d0 53 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74  S option activat
1c0e0 65 73 20 6f 72 20 64 65 61 63 74 69 76 61 74 65  es or deactivate
1c0f0 73 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20  s.** the legacy 
1c100 5b 64 6f 75 62 6c 65 2d 71 75 6f 74 65 64 20 73  [double-quoted s
1c110 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 5d 20 6d  tring literal] m
1c120 69 73 66 65 61 74 75 72 65 20 66 6f 72 20 44 44  isfeature for DD
1c130 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a  L statements,.**
1c140 20 73 75 63 68 20 61 73 20 43 52 45 41 54 45 20   such as CREATE 
1c150 54 41 42 4c 45 20 61 6e 64 20 43 52 45 41 54 45  TABLE and CREATE
1c160 20 49 4e 44 45 58 2e 20 54 68 65 0a 2a 2a 20 64   INDEX. The.** d
1c170 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66 20  efault value of 
1c180 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20  this setting is 
1c190 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
1c1a0 65 20 5b 2d 44 53 51 4c 49 54 45 5f 44 51 53 5d  e [-DSQLITE_DQS]
1c1b0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
1c1c0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 64   option..** </dd
1c1d0 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  >.** </dl>.*/.#d
1c1e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1c1f0 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45  ONFIG_MAINDBNAME
1c200 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 30              1000
1c210 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20   /* const char* 
1c220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c230 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
1c240 53 49 44 45 20 20 20 20 20 20 20 20 20 20 20 20  SIDE            
1c250 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69   1001 /* void* i
1c260 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
1c270 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1c280 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20  G_ENABLE_FKEY   
1c290 20 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20          1002 /* 
1c2a0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1c2b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1c2c0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
1c2d0 45 52 20 20 20 20 20 20 20 20 31 30 30 33 20 2f  ER        1003 /
1c2e0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1c2f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1c300 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53  ONFIG_ENABLE_FTS
1c310 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34  3_TOKENIZER 1004
1c320 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1c330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c340 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c  BCONFIG_ENABLE_L
1c350 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30  OAD_EXTENSION 10
1c360 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  05 /* int int* *
1c370 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c380 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50  _DBCONFIG_NO_CKP
1c390 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20  T_ON_CLOSE      
1c3a0 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1006 /* int int*
1c3b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c3c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1c3d0 4c 45 5f 51 50 53 47 20 20 20 20 20 20 20 20 20  LE_QPSG         
1c3e0 20 20 31 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e    1007 /* int in
1c3f0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1c400 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52  LITE_DBCONFIG_TR
1c410 49 47 47 45 52 5f 45 51 50 20 20 20 20 20 20 20  IGGER_EQP       
1c420 20 20 20 20 31 30 30 38 20 2f 2a 20 69 6e 74 20      1008 /* int 
1c430 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1c440 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1c450 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 20 20  RESET_DATABASE  
1c460 20 20 20 20 20 20 31 30 30 39 20 2f 2a 20 69 6e        1009 /* in
1c470 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1c480 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1c490 47 5f 44 45 46 45 4e 53 49 56 45 20 20 20 20 20  G_DEFENSIVE     
1c4a0 20 20 20 20 20 20 20 20 31 30 31 30 20 2f 2a 20          1010 /* 
1c4b0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1c4c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1c4d0 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53 43 48  FIG_WRITABLE_SCH
1c4e0 45 4d 41 20 20 20 20 20 20 20 31 30 31 31 20 2f  EMA       1011 /
1c4f0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1c500 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1c510 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54  ONFIG_LEGACY_ALT
1c520 45 52 5f 54 41 42 4c 45 20 20 20 20 31 30 31 32  ER_TABLE    1012
1c530 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1c540 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c550 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 4d 4c 20  BCONFIG_DQS_DML 
1c560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30                10
1c570 31 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  13 /* int int* *
1c580 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c590 5f 44 42 43 4f 4e 46 49 47 5f 44 51 53 5f 44 44  _DBCONFIG_DQS_DD
1c5a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  L               
1c5b0 31 30 31 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1014 /* int int*
1c5c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c5d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1c5e0 4c 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  LE_VIEW         
1c5f0 20 20 31 30 31 35 20 2f 2a 20 69 6e 74 20 69 6e    1015 /* int in
1c600 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1c610 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
1c620 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  X               
1c630 20 20 20 20 31 30 31 35 20 2f 2a 20 4c 61 72 67      1015 /* Larg
1c640 65 73 74 20 44 42 43 4f 4e 46 49 47 20 2a 2f 0a  est DBCONFIG */.
1c650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c660 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
1c670 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
1c680 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
1c690 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c6a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1c6b0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
1c6c0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
1c6d0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
1c6e0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
1c6f0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
1c700 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
1c710 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
1c720 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
1c730 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
1c740 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
1c750 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
1c760 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
1c770 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1c780 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
1c790 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
1c7a0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
1c7b0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
1c7c0 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44   Rowid.** METHOD
1c7d0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1c7e0 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
1c7f0 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
1c800 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
1c810 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
1c820 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
1c830 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
1c840 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
1c850 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
1c860 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
1c870 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
1c880 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
1c890 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
1c8a0 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
1c8b0 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
1c8c0 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
1c8d0 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
1c8e0 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
1c8f0 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
1c900 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
1c910 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
1c920 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
1c930 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
1c940 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
1c950 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
1c960 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
1c970 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
1c980 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
1c990 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1c9a0 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
1c9b0 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65  rface usually re
1c9c0 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
1c9d0 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74  ] of.** the most
1c9e0 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
1c9f0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
1ca00 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
1ca10 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
1ca20 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
1ca30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e   connection D. ^
1ca40 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
1ca50 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
1ca60 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  les are not.** r
1ca70 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20  ecorded. ^If no 
1ca80 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
1ca90 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
1caa0 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72  tables have ever
1cab0 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e   occurred .** on
1cac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1cad0 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e  nnection D, then
1cae0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1caf0 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
1cb00 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a  turns .** zero..
1cb10 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73  **.** As well as
1cb20 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d   being set autom
1cb30 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73  atically as rows
1cb40 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e   are inserted in
1cb50 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74  to database.** t
1cb60 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65  ables, the value
1cb70 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
1cb80 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  s function may b
1cb90 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79  e set explicitly
1cba0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
1cbb0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1cbc0 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53  rowid()].**.** S
1cbd0 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ome virtual tabl
1cbe0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1cbf0 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77  s may INSERT row
1cc00 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
1cc10 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  les as.** part o
1cc20 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74  f committing a t
1cc30 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e  ransaction (e.g.
1cc40 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61   to flush data a
1cc50 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65  ccumulated in me
1cc60 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29  mory.** to disk)
1cc70 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73  . In this case s
1cc80 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1cc90 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
1cca0 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69   return the rowi
1ccb0 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  d.** associated 
1ccc0 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72  with these inter
1ccd0 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61  nal INSERT opera
1cce0 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61  tions, which lea
1ccf0 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75  ds to .** unintu
1cd00 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56  itive results. V
1cd10 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
1cd20 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61  lementations tha
1cd30 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f  t do write to ro
1cd40 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e  wid.** tables in
1cd50 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76   this way can av
1cd60 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d  oid this problem
1cd70 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68   by restoring th
1cd80 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72  e original .** r
1cd90 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67  owid value using
1cda0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
1cdb0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1cdc0 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  )] before return
1cdd0 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20  ing .** control 
1cde0 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a  to the user..**.
1cdf0 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
1ce00 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
1ce10 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e  n a trigger then
1ce20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1ce30 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ll .** return th
1ce40 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
1ce50 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73   inserted row as
1ce60 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
1ce70 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e  gger is .** runn
1ce80 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72  ing. Once the tr
1ce90 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e  igger program en
1cea0 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
1ceb0 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
1cec0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
1ced0 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
1cee0 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
1cef0 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29  gger was fired.)
1cf00 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
1cf10 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
1cf20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
1cf30 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
1cf40 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
1cf50 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
1cf60 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
1cf70 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
1cf80 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
1cf90 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
1cfa0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
1cfb0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
1cfc0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
1cfd0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
1cfe0 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
1cff0 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
1d000 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1d010 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
1d020 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
1d030 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
1d040 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
1d050 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
1d060 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
1d070 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
1d080 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
1d090 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
1d0a0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
1d0b0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
1d0c0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
1d0d0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
1d0e0 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
1d0f0 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
1d100 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
1d110 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
1d120 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
1d130 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1d140 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
1d150 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
1d160 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
1d170 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
1d180 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
1d190 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
1d1a0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
1d1b0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
1d1c0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
1d1d0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
1d1e0 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
1d1f0 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
1d200 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
1d210 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
1d220 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1d230 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1d240 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
1d250 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
1d260 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
1d270 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
1d280 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
1d290 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1d2a0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
1d2b0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
1d2c0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
1d2d0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1d2e0 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
1d2f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1d300 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
1d310 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1d320 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
1d330 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
1d340 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
1d350 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
1d360 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
1d370 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
1d380 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1d390 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1d3a0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
1d3b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d3c0 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49  : Set the Last I
1d3d0 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75  nsert Rowid valu
1d3e0 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  e..** METHOD: sq
1d3f0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
1d400 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1d410 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c  _insert_rowid(D,
1d420 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77   R) method allow
1d430 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
1d440 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20  n to.** set the 
1d450 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1d460 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  y calling sqlite
1d470 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1d480 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20  wid(D) to R .** 
1d490 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e  without insertin
1d4a0 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65  g a row into the
1d4b0 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f   database..*/.vo
1d4c0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  id sqlite3_set_l
1d4d0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1d4e0 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65  (sqlite3*,sqlite
1d4f0 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
1d500 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
1d510 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
1d520 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1d530 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1d540 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1d550 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1d560 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1d570 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
1d580 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1d590 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
1d5a0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
1d5b0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1d5c0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
1d5d0 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
1d5e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d5f0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1d600 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1d610 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
1d620 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1d630 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
1d640 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
1d650 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
1d660 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
1d670 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
1d680 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1d690 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
1d6a0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1d6b0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1d6c0 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
1d6d0 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
1d6e0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
1d6f0 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
1d700 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
1d710 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
1d720 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
1d730 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1d740 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1d750 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1d760 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
1d770 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1d780 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1d790 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
1d7a0 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
1d7b0 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
1d7c0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
1d7d0 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
1d7e0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1d7f0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
1d800 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
1d810 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1d820 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
1d830 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
1d840 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
1d850 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
1d860 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
1d870 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
1d880 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1d890 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
1d8a0 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
1d8b0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1d8c0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
1d8d0 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
1d8e0 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
1d8f0 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
1d900 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
1d910 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
1d920 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
1d930 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1d940 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
1d950 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
1d960 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
1d970 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
1d980 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
1d990 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
1d9a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1d9b0 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
1d9c0 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
1d9d0 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
1d9e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1d9f0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
1da00 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1da10 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
1da20 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1da30 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
1da40 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
1da50 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
1da60 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
1da70 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
1da80 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
1da90 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
1daa0 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
1dab0 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
1dac0 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
1dad0 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
1dae0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1daf0 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1db00 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
1db10 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
1db20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
1db30 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
1db40 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
1db50 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
1db60 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
1db70 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
1db80 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1db90 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
1dba0 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
1dbb0 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
1dbc0 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
1dbd0 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
1dbe0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
1dbf0 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
1dc00 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
1dc10 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
1dc20 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
1dc30 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
1dc40 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
1dc50 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1dc60 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1dc70 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
1dc80 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1dc90 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
1dca0 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
1dcb0 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
1dcc0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
1dcd0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
1dce0 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
1dcf0 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
1dd00 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1dd10 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
1dd20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1dd30 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
1dd40 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1dd50 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
1dd60 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
1dd70 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1dd80 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1dd90 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
1dda0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  rigger..**.** If
1ddb0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1ddc0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1ddd0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1dde0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ddf0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1de00 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
1de10 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1de20 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1de30 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
1de40 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1de50 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ningful..**.** S
1de60 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e  ee also:.** <ul>
1de70 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71  .** <li> the [sq
1de80 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1de90 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1dea0 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f  .** <li> the [co
1deb0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1dec0 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  ma].** <li> the 
1ded0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1dee0 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e  unction].** <li>
1def0 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69   the [data_versi
1df00 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 2f  on pragma].** </
1df10 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul>.*/.int sqlit
1df20 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
1df30 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1df40 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
1df50 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1df60 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
1df70 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1df80 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1df90 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
1dfa0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
1dfb0 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64  serted, modified
1dfc0 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
1dfd0 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20  y all [INSERT], 
1dfe0 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
1dff0 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
1e000 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e  completed.** sin
1e010 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
1e020 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f  connection was o
1e030 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67  pened, including
1e040 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20   those executed 
1e050 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72  as.** part of tr
1e060 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
1e070 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1e080 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1e090 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f   statement.** do
1e0a0 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68  es not affect th
1e0b0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1e0c0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
1e0d0 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20  l_changes()..** 
1e0e0 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64  .** ^Changes mad
1e0f0 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f  e as part of [fo
1e100 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
1e110 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  s] are included 
1e120 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c  in the.** count,
1e130 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20   but those made 
1e140 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41  as part of REPLA
1e150 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  CE constraint re
1e160 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20  solution are.** 
1e170 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f  not. ^Changes to
1e180 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1e190 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1e1a0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1e1b0 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ers .** are not 
1e1c0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1e1d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
1e1e0 6c 5f 63 68 61 6e 67 65 73 28 44 29 5d 20 69 6e  l_changes(D)] in
1e1f0 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70  terface only rep
1e200 6f 72 74 73 20 74 68 65 20 6e 75 6d 62 65 72 0a  orts the number.
1e210 2a 2a 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20  ** of rows that 
1e220 63 68 61 6e 67 65 64 20 64 75 65 20 74 6f 20 53  changed due to S
1e230 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  QL statement run
1e240 20 61 67 61 69 6e 73 74 20 64 61 74 61 62 61 73   against databas
1e250 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
1e260 44 2e 20 20 41 6e 79 20 63 68 61 6e 67 65 73 20  D.  Any changes 
1e270 62 79 20 6f 74 68 65 72 20 64 61 74 61 62 61 73  by other databas
1e280 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 72  e connections ar
1e290 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 54 6f  e ignored..** To
1e2a0 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20   detect changes 
1e2b0 61 67 61 69 6e 73 74 20 61 20 64 61 74 61 62 61  against a databa
1e2c0 73 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f 74 68  se file from oth
1e2d0 65 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  er database.** c
1e2e0 6f 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65 20 74  onnections use t
1e2f0 68 65 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f  he [PRAGMA data_
1e300 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64  version] command
1e310 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   or the.** [SQLI
1e320 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45  TE_FCNTL_DATA_VE
1e330 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e  RSION] [file con
1e340 74 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  trol]..** .** If
1e350 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1e360 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1e370 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1e380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e390 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1e3a0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1e3b0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1e3c0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
1e3d0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
1e3e0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1e3f0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1e400 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a  *.** See also:.*
1e410 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74  * <ul>.** <li> t
1e420 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
1e430 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1e440 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f  .** <li> the [co
1e450 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1e460 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  ma].** <li> the 
1e470 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1e480 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e  unction].** <li>
1e490 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69   the [data_versi
1e4a0 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c  on pragma].** <l
1e4b0 69 3e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  i> the [SQLITE_F
1e4c0 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f  CNTL_DATA_VERSIO
1e4d0 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  N] [file control
1e4e0 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ].** </ul>.*/.in
1e4f0 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
1e500 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1e510 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e520 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
1e530 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
1e540 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ry.** METHOD: sq
1e550 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1e560 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
1e570 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
1e580 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1e590 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
1e5a0 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
1e5b0 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
1e5c0 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
1e5d0 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
1e5e0 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
1e5f0 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
1e600 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
1e610 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
1e620 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
1e630 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
1e640 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
1e650 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
1e660 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
1e670 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
1e680 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1e690 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
1e6a0 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
1e6b0 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
1e6c0 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
1e6d0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
1e6e0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
1e6f0 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
1e700 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
1e710 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1e720 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1e730 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
1e740 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
1e750 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
1e760 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
1e770 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
1e780 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
1e790 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1e7a0 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
1e7b0 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
1e7c0 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
1e7d0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
1e7e0 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
1e7f0 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
1e800 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
1e810 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
1e820 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
1e830 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
1e840 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
1e850 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
1e860 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
1e870 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
1e880 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
1e890 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
1e8a0 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
1e8b0 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
1e8c0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
1e8d0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
1e8e0 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
1e8f0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
1e900 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
1e910 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
1e920 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
1e930 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
1e940 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
1e950 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1e960 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
1e970 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
1e980 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1e990 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1e9a0 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
1e9b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
1e9c0 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
1e9d0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1e9e0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1e9f0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1ea00 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ea10 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
1ea20 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
1ea30 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
1ea40 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
1ea50 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
1ea60 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
1ea70 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
1ea80 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1ea90 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1eaa0 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
1eab0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1eac0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1ead0 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
1eae0 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
1eaf0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
1eb00 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
1eb10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1eb20 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
1eb30 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1eb40 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
1eb50 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
1eb60 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
1eb70 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1eb80 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
1eb90 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
1eba0 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
1ebb0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1ebc0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1ebd0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1ebe0 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
1ebf0 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ns..*/.void sqli
1ec00 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
1ec10 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1ec20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
1ec30 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
1ec40 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
1ec50 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
1ec60 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
1ec70 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
1ec80 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
1ec90 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
1eca0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
1ecb0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
1ecc0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
1ecd0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1ece0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
1ecf0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
1ed00 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
1ed10 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
1ed20 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
1ed30 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
1ed40 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1ed50 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
1ed60 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
1ed70 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
1ed80 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1ed90 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
1eda0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
1edb0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
1edc0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
1edd0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
1ede0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
1edf0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
1ee00 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
1ee10 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
1ee20 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
1ee30 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
1ee40 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
1ee50 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
1ee60 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
1ee70 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
1ee80 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
1ee90 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
1eea0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
1eeb0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
1eec0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
1eed0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
1eee0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
1eef0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
1ef00 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
1ef10 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
1ef20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
1ef30 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
1ef40 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
1ef50 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
1ef60 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1ef70 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
1ef80 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
1ef90 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
1efa0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1efb0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
1efc0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
1efd0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
1efe0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
1eff0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
1f000 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
1f010 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
1f020 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
1f030 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
1f040 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
1f050 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
1f060 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
1f070 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
1f080 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
1f090 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
1f0a0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1f0b0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
1f0c0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
1f0d0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
1f0e0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
1f0f0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1f100 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
1f110 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
1f120 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
1f130 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1f140 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1f150 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
1f160 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
1f170 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1f180 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
1f190 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
1f1a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
1f1b0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1f1c0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
1f1d0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1f1e0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
1f1f0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
1f200 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1f210 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
1f220 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1f230 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1f240 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
1f250 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1f260 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1f270 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
1f280 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
1f290 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1f2a0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
1f2b0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
1f2c0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
1f2d0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
1f2e0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
1f2f0 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  Errors.** KEYWOR
1f300 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65  DS: {busy-handle
1f310 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73  r callback} {bus
1f320 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45  y handler}.** ME
1f330 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1f340 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f350 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c  _busy_handler(D,
1f360 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74  X,P) routine set
1f370 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1f380 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20  ction X.** that 
1f390 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1f3a0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
1f3b0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
1f3c0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
1f3d0 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61  to access a data
1f3e0 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63  base table assoc
1f3f0 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64  iated with.** [d
1f400 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f410 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68  on] D when anoth
1f420 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
1f430 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20  process has the 
1f440 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  table locked..**
1f450 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73   The sqlite3_bus
1f460 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65  y_handler() inte
1f470 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
1f480 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73   implement.** [s
1f490 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1f4a0 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47  out()] and [PRAG
1f4b0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
1f4c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1f4d0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1f4e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
1f4f0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20  ITE_BUSY].** is 
1f500 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1f510 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
1f520 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
1f530 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
1f540 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
1f550 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
1f560 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
1f570 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1f580 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
1f590 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1f5a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1f5b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1f5c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
1f5d0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
1f5e0 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
1f5f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
1f600 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1f610 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
1f620 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
1f630 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1f640 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1f650 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
1f660 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
1f670 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
1f680 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65  been invoked pre
1f690 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20  viously for the 
1f6a0 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65  same locking eve
1f6b0 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
1f6c0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
1f6d0 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
1f6e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
1f6f0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
1f700 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
1f710 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
1f720 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74  ITE_BUSY] is ret
1f730 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  urned.** to the 
1f740 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20  application..** 
1f750 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
1f760 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1f770 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
1f780 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
1f790 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  de to access the
1f7a0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68   database and th
1f7b0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
1f7c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
1f7d0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
1f7e0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
1f7f0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
1f800 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
1f810 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
1f820 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
1f830 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
1f840 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
1f850 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
1f860 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
1f870 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
1f880 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
1f890 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
1f8a0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
1f8b0 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1f8c0 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f  cation instead o
1f8d0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a  f invoking the .
1f8e0 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  ** busy handler.
1f8f0 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
1f900 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
1f910 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
1f920 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
1f930 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
1f940 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
1f950 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
1f960 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
1f970 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
1f980 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
1f990 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
1f9a0 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
1f9b0 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
1f9c0 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
1f9d0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1f9e0 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
1f9f0 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
1fa00 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
1fa10 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
1fa20 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
1fa30 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
1fa40 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1fa50 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
1fa60 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
1fa70 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
1fa80 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1fa90 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
1faa0 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
1fab0 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
1fac0 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
1fad0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
1fae0 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
1faf0 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
1fb00 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
1fb10 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
1fb20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
1fb30 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
1fb40 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
1fb50 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1fb60 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
1fb70 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1fb80 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1fb90 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   NULL..**.** ^(T
1fba0 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1fbb0 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1fbc0 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
1fbd0 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
1fbe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1fbf0 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
1fc00 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
1fc10 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
1fc20 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
1fc30 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
1fc40 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
1fc50 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1fc60 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74  )].** or evaluat
1fc70 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79  ing [PRAGMA busy
1fc80 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c  _timeout=N] will
1fc90 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62   change the.** b
1fca0 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20  usy handler and 
1fcb0 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70  thus clear any p
1fcc0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75  reviously set bu
1fcd0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
1fce0 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
1fcf0 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
1fd00 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
1fd10 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
1fd20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1fd30 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1fd40 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1fd50 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72  ndler.  In other
1fd60 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62   words,.** the b
1fd70 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e  usy handler is n
1fd80 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41  ot reentrant.  A
1fd90 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
1fda0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
1fdb0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
1fdc0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
1fdd0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1fde0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
1fdf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1fe00 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
1fe10 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
1fe20 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1fe30 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
1fe40 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1fe50 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74  ler(sqlite3*,int
1fe60 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76  (*)(void*,int),v
1fe70 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1fe80 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1fe90 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45  sy Timeout.** ME
1fea0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1feb0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1fec0 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1fed0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1fee0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1fef0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1ff00 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1ff10 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1ff20 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1ff30 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1ff40 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1ff50 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1ff60 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1ff70 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1ff80 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1ff90 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1ffa0 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1ffb0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1ffc0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1ffd0 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1ffe0 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1fff0 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
20000 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
20010 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
20020 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
20030 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
20040 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
20050 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
20060 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
20070 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
20080 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
20090 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
200a0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
200b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
200c0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
200d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
200e0 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
200f0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
20100 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
20110 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
20120 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
20130 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
20140 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
20150 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
20160 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
20170 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
20180 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
20190 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
201a0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
201b0 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
201c0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
201d0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
201e0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
201f0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
20200 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
20210 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
20220 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
20230 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
20240 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
20250 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
20260 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
20270 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
20280 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
20290 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
202a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
202b0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
202c0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
202d0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
202e0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
202f0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
20300 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
20310 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
20320 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
20330 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
20340 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
20350 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
20360 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
20370 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
20380 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
20390 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
203a0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
203b0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
203c0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
203d0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
203e0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
203f0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
20400 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
20410 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
20420 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
20430 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
20440 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
20450 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
20460 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
20470 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
20480 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
20490 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
204a0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
204b0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
204c0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
204d0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
204e0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
204f0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
20500 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
20510 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
20520 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
20530 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
20540 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
20550 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
20560 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
20570 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
20580 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
20590 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
205a0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
205b0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
205c0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
205d0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
205e0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
205f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
20600 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
20610 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
20620 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
20630 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
20640 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
20650 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
20660 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
20670 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
20680 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
20690 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
206a0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
206b0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
206c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
206d0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
206e0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
206f0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
20700 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
20710 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
20720 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
20730 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
20740 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
20750 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
20760 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
20770 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
20780 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
20790 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
207a0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
207b0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
207c0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
207d0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
207e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
207f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
20800 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
20810 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
20820 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
20830 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
20840 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
20850 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
20860 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
20870 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
20880 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
20890 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
208a0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
208b0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
208c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
208d0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
208e0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
208f0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
20900 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
20910 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
20920 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
20930 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
20940 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
20950 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
20960 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
20970 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
20980 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
20990 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
209a0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
209b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
209c0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
209d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
209e0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
209f0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
20a00 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
20a10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
20a20 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
20a30 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
20a40 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
20a50 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
20a60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
20a70 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
20a80 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
20a90 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
20aa0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
20ab0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
20ac0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
20ad0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
20ae0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
20af0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
20b00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
20b10 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
20b20 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
20b30 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
20b40 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
20b50 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
20b60 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
20b70 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
20b80 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
20b90 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
20ba0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
20bb0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
20bc0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
20bd0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
20be0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
20bf0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
20c00 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
20c10 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
20c20 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
20c30 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
20c40 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
20c50 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
20c60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
20c70 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
20c80 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
20c90 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
20ca0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
20cb0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
20cc0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
20cd0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
20ce0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
20cf0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
20d00 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
20d10 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
20d20 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
20d30 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
20d40 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
20d50 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
20d60 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
20d70 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
20d80 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
20d90 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
20da0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
20db0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
20dc0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
20dd0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
20de0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
20df0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
20e00 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
20e10 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
20e20 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
20e30 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
20e40 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
20e50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
20e60 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
20e70 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
20e80 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
20e90 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
20ea0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
20eb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
20ec0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
20ed0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
20ee0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
20ef0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
20f00 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
20f10 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
20f20 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
20f30 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
20f40 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
20f50 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
20f60 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
20f70 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
20f80 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
20f90 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
20fa0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
20fb0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
20fc0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
20fd0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
20fe0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
20ff0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
21000 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
21010 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
21020 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
21030 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
21040 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
21050 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
21060 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
21070 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
21080 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
21090 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65   library..** The
210a0 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65  se routines unde
210b0 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74  rstand most of t
210c0 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d 61 74  he common format
210d0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f  ting options fro
210e0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
210f0 64 20 6c 69 62 72 61 72 79 20 70 72 69 6e 74 66  d library printf
21100 28 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65  () .** plus some
21110 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d   additional non-
21120 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73  standard formats
21130 20 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20 5b 25   ([%q], [%Q], [%
21140 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e 0a 2a  w], and [%z])..*
21150 2a 20 53 65 65 20 74 68 65 20 5b 62 75 69 6c 74  * See the [built
21160 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 20 64 6f  -in printf()] do
21170 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
21180 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  details..**.** ^
21190 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
211a0 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
211b0 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
211c0 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
211d0 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
211e0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
211f0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
21200 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a 2a 20  malloc64()]..** 
21210 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
21220 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
21230 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
21240 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
21250 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
21260 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
21270 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
21280 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
21290 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
212a0 63 36 34 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  c64()] is unable
212b0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
212c0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
212d0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
212e0 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
212f0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
21300 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
21310 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
21320 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
21330 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
21340 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
21350 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
21360 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
21370 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
21380 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
21390 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
213a0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
213b0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
213c0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
213d0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
213e0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
213f0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
21400 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
21410 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
21420 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
21430 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
21440 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
21450 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
21460 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
21470 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
21480 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
21490 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
214a0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
214b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
214c0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
214d0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
214e0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
214f0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
21500 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
21510 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
21520 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
21530 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
21540 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
21550 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
21560 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
21570 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
21580 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
21590 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
215a0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
215b0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
215c0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
215d0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
215e0 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
215f0 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
21600 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
21610 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
21620 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
21630 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
21640 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
21650 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
21660 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
21670 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
21680 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
21690 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
216a0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
216b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
216c0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
216d0 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
216e0 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
216f0 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
21700 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
21710 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
21720 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
21730 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
21740 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
21750 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
21760 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
21770 6f 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72  o:  [built-in pr
21780 69 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e 74 66  intf()], [printf
21790 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
217a0 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
217b0 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
217c0 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
217d0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
217e0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
217f0 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
21800 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
21810 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
21820 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
21830 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
21840 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
21850 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
21860 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
21870 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
21880 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
21890 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
218a0 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
218b0 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
218c0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
218d0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
218e0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
218f0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
21900 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
21910 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
21920 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
21930 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
21940 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
21950 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
21960 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
21970 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
21980 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
21990 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
219a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
219b0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
219c0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
219d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
219e0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
219f0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
21a00 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
21a10 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
21a20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
21a30 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
21a40 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
21a50 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
21a60 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
21a70 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
21a80 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
21a90 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
21aa0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
21ab0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
21ac0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
21ad0 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
21ae0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
21af0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
21b00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
21b10 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
21b20 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
21b30 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
21b40 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
21b50 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
21b60 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
21b70 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
21b80 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
21b90 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
21ba0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
21bb0 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
21bc0 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
21bd0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
21be0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
21bf0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
21c00 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
21c10 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
21c20 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
21c30 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
21c40 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
21c50 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
21c60 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
21c70 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
21c80 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
21c90 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
21ca0 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
21cb0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
21cc0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
21cd0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
21ce0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
21cf0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
21d00 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
21d10 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
21d20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
21d30 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
21d40 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
21d50 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
21d60 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
21d70 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
21d80 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
21d90 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
21da0 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
21db0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
21dc0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
21dd0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
21de0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
21df0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
21e00 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
21e10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
21e20 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
21e30 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
21e40 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
21e50 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
21e60 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
21e70 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
21e80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
21e90 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
21ea0 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
21eb0 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
21ec0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
21ed0 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
21ee0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
21ef0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
21f00 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
21f10 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
21f20 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
21f30 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
21f40 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
21f50 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
21f60 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
21f70 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
21f80 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
21f90 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
21fa0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
21fb0 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
21fc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
21fd0 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
21fe0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
21ff0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
22000 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
22010 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
22020 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
22030 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
22040 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
22050 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
22060 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
22070 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
22080 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
22090 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
220a0 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
220b0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
220c0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
220d0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
220e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
220f0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
22100 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
22110 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
22120 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
22130 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
22140 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
22150 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
22160 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
22170 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
22180 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
22190 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
221a0 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
221b0 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
221c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
221d0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
221e0 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
221f0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
22200 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
22210 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
22220 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
22230 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
22240 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
22250 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
22260 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
22270 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
22280 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
22290 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
222a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
222b0 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
222c0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
222d0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
222e0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
222f0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
22300 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
22310 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
22320 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
22330 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
22340 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
22350 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
22360 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
22370 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
22380 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
22390 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
223a0 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
223b0 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
223c0 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
223d0 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
223e0 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
223f0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
22400 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
22410 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
22420 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
22430 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
22440 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
22450 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
22460 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
22470 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
22480 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
22490 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
224a0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
224b0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
224c0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
224d0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
224e0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
224f0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
22500 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
22510 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
22520 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
22530 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
22540 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
22550 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
22560 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
22570 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
22580 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
22590 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
225a0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
225b0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
225c0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
225d0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
225e0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
225f0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
22600 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
22610 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
22620 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
22630 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
22640 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
22650 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
22660 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
22670 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
22680 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
22690 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
226a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
226b0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
226c0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
226d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
226e0 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
226f0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
22700 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
22710 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
22720 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
22730 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
22740 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
22750 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
22760 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
22770 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
22780 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
22790 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
227a0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
227b0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
227c0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
227d0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
227e0 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
227f0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
22800 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
22810 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
22820 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
22830 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
22840 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
22850 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
22860 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
22870 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
22880 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
22890 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
228a0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
228b0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
228c0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
228d0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
228e0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
228f0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
22900 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
22910 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
22920 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
22930 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
22940 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
22950 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
22960 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
22970 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
22980 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
22990 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
229a0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
229b0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
229c0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
229d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
229e0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
229f0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
22a00 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
22a10 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
22a20 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  t64);.void *sqli
22a30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
22a40 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  *, int);.void *s
22a50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
22a60 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f  (void*, sqlite3_
22a70 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  uint64);.void sq
22a80 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
22a90 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  );.sqlite3_uint6
22aa0 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
22ab0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
22ac0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
22ad0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
22ae0 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
22af0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
22b00 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
22b10 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
22b20 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
22b30 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
22b40 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
22b50 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
22b60 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
22b70 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
22b80 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
22b90 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
22ba0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
22bb0 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
22bc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
22bd0 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
22be0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
22bf0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
22c00 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
22c10 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
22c20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
22c30 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
22c40 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
22c50 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
22c60 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
22c70 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
22c80 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
22c90 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
22ca0 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
22cb0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
22cc0 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
22cd0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
22ce0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
22cf0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
22d00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
22d10 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
22d20 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
22d30 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
22d40 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
22d50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
22d60 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
22d70 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
22d80 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
22d90 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
22da0 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
22db0 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
22dc0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
22dd0 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
22de0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
22df0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
22e00 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
22e10 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
22e20 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
22e30 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
22e40 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
22e50 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
22e60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
22e70 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
22e80 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
22e90 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
22ea0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
22eb0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
22ec0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
22ed0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
22ee0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
22ef0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
22f00 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
22f10 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
22f20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
22f30 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
22f40 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
22f50 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
22f60 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
22f70 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
22f80 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
22f90 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
22fa0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
22fb0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
22fc0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
22fd0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
22fe0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
22ff0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
23000 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
23010 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
23020 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
23030 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
23040 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
23050 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
23060 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
23070 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
23080 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
23090 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
230a0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
230b0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
230c0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
230d0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
230e0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
230f0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
23100 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
23110 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
23120 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
23130 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
23140 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
23150 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
23160 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
23170 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
23180 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
23190 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
231a0 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
231b0 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
231c0 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
231d0 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
231e0 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
231f0 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
23200 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
23210 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
23220 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
23230 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
23240 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
23250 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
23260 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
23270 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
23280 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
23290 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
232a0 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
232b0 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
232c0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
232d0 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
232e0 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
232f0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
23300 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
23310 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
23320 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
23330 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
23340 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
23350 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
23360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
23370 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
23380 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
23390 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
233a0 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44  lite3.** KEYWORD
233b0 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63  S: {authorizer c
233c0 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e  allback}.**.** ^
233d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
233e0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
233f0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
23400 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
23410 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
23420 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
23430 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
23440 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
23450 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
23460 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
23470 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
23480 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
23490 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
234a0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
234b0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
234c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
234d0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
234e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
234f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
23500 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  are16()], [sqlit
23510 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
23520 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  )],.** and [sqli
23530 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
23540 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
23550 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
23560 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
23570 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
23580 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
23590 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
235a0 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
235b0 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
235c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
235d0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
235e0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
235f0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
23600 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
23610 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
23620 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
23630 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
23640 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
23650 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
23660 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
23670 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
23680 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
23690 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
236a0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
236b0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
236c0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
236d0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
236e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
236f0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
23700 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
23710 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
23720 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
23730 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
23740 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
23750 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
23760 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
23770 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
23780 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
23790 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
237a0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
237b0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
237c0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
237d0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
237e0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
237f0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
23800 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
23810 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
23820 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
23830 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
23840 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
23850 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
23860 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
23870 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
23880 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23890 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
238a0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
238b0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
238c0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
238d0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
238e0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
238f0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
23900 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
23910 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
23920 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
23930 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
23940 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
23950 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
23960 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
23970 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
23980 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
23990 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
239a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
239b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
239c0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
239d0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
239e0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
239f0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
23a00 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
23a10 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
23a20 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
23a30 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
23a40 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
23a50 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68  allback are eith
23a60 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  er NULL pointers
23a70 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   or zero-termina
23a80 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74  ted strings.** t
23a90 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
23aa0 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
23ab0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
23ac0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
23ad0 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
23ae0 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65  s must always be
23af0 20 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63   prepared to enc
23b00 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f  ounter a NULL po
23b10 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20  inter in any.** 
23b20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72  of the third thr
23b30 6f 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70  ough the sixth p
23b40 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
23b50 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
23b60 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
23b70 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
23b80 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
23b90 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
23ba0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
23bb0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
23bc0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
23bd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23be0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
23bf0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
23c00 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
23c10 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
23c20 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
23c30 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
23c40 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
23c50 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
23c60 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
23c70 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
23c80 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
23c90 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
23ca0 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
23cb0 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
23cc0 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
23cd0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
23ce0 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ble..** ^When a 
23cf0 74 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e  table is referen
23d00 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54  ced by a [SELECT
23d10 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20  ] but no column 
23d20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78  values are.** ex
23d30 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61  tracted from tha
23d40 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61  t table (for exa
23d50 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20  mple in a query 
23d60 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20  like.** "SELECT 
23d70 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61  count(*) FROM ta
23d80 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51  b") then the [SQ
23d90 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f  LITE_READ] autho
23da0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
23db0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  * is invoked onc
23dc0 65 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65  e for that table
23dd0 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e   with a column n
23de0 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65  ame that is an e
23df0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  mpty string..** 
23e00 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
23e10 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
23e20 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
23e30 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
23e40 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
23e50 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
23e60 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
23e70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
23e80 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
23e90 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
23ea0 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
23eb0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
23ec0 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
23ed0 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
23ee0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
23ef0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
23f00 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
23f10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
23f20 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
23f30 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
23f40 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
23f50 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
23f60 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
23f70 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
23f80 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
23f90 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
23fa0 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
23fb0 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
23fc0 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
23fd0 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
23fe0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
23ff0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
24000 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
24010 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
24020 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
24030 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
24040 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
24050 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
24060 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
24070 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
24080 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
24090 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
240a0 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
240b0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
240c0 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
240d0 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
240e0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
240f0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
24100 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
24110 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
24120 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
24130 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
24140 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
24150 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
24160 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
24170 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
24180 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
24190 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
241a0 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
241b0 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
241c0 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
241d0 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
241e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
241f0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
24200 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
24210 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
24220 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
24230 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
24240 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
24250 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
24260 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
24270 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
24280 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
24290 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
242a0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
242b0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
242c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
242d0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
242e0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
242f0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
24300 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
24310 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
24320 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
24330 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
24340 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
24350 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
24360 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
24370 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
24380 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
24390 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
243a0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
243b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
243c0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
243d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
243e0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
243f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24400 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
24410 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
24420 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
24430 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
24440 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
24450 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
24460 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
24470 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
24480 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
24490 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
244a0 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
244b0 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
244c0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
244d0 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
244e0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
244f0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
24500 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
24510 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
24520 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
24530 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
24540 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
24550 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
24560 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
24570 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
24580 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
24590 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
245a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
245b0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
245c0 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
245d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
245e0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
245f0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
24600 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
24610 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
24620 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
24630 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
24640 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
24650 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
24660 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
24670 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
24680 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
24690 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
246a0 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
246b0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
246c0 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
246d0 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
246e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
246f0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
24700 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
24710 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
24720 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
24730 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
24740 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
24750 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
24760 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
24770 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
24780 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
24790 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
247a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
247b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
247c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
247d0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
247e0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
247f0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
24800 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
24810 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
24820 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
24830 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
24840 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
24850 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
24860 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
24870 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
24880 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
24890 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
248a0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
248b0 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
248c0 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
248d0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
248e0 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
248f0 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
24900 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
24910 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
24920 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
24930 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
24940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
24950 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
24960 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
24970 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
24980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24990 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
249a0 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
249b0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
249c0 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
249d0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
249e0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
249f0 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
24a00 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
24a10 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
24a20 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
24a30 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
24a40 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
24a50 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
24a60 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
24a70 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
24a80 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
24a90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
24aa0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
24ab0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
24ac0 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
24ad0 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
24ae0 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
24af0 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
24b00 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
24b10 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
24b20 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
24b30 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
24b40 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
24b50 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
24b60 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
24b70 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
24b80 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
24b90 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
24ba0 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
24bb0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
24bc0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
24bd0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
24be0 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
24bf0 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
24c00 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
24c10 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
24c20 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
24c30 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
24c40 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
24c50 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
24c60 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
24c70 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
24c80 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
24c90 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
24ca0 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
24cb0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
24cc0 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
24cd0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
24ce0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
24cf0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
24d00 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
24d10 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
24d20 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
24d30 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
24d40 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
24d50 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
24d60 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
24d70 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
24d80 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
24d90 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   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 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
24dd0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
24de0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
24df0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
24e00 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
24e10 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
24e20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
24e30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24e40 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
24e50 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
24e60 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24e70 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24e80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24e90 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
24ea0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
24eb0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
24ec0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24ed0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24ee0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
24ef0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
24f00 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
24f10 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24f20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24f30 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
24f40 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
24f50 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
24f60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24f70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24f80 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
24f90 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
24fa0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
24fb0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24fc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24fd0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
24fe0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
24ff0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
25000 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
25010 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
25020 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
25030 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
25040 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
25050 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
25060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25070 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
25080 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
25090 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
250a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
250b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
250c0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
250d0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
250e0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
250f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
25100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
25110 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
25120 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
25130 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
25140 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
25150 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
25160 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
25170 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
25180 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
25190 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
251a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
251b0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
251c0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
251d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
251e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
251f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
25200 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
25210 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
25220 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
25230 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
25240 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
25250 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
25260 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
25270 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
25280 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
25290 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
252a0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
252b0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
252c0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
252d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
252e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
252f0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
25300 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
25310 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
25320 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
25330 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
25340 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
25350 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
25360 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
25370 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
25380 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
25390 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
253a0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
253b0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
253c0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
253d0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
253e0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
253f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
25400 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
25410 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
25420 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
25430 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
25440 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
25450 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
25460 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
25470 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
25480 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
25490 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
254a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
254b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
254c0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
254d0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
254e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
254f0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
25500 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
25510 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
25520 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
25530 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
25540 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
25550 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25560 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
25570 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
25580 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
25590 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
255a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
255b0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
255c0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
255d0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
255e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
255f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
25600 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
25610 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
25620 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
25630 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
25640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
25650 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
25660 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
25670 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
25680 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
25690 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
256a0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
256b0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
256c0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
256d0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
256e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
256f0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
25700 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
25710 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
25720 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
25730 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
25740 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
25750 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
25760 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
25770 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
25780 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
25790 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
257a0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
257b0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
257c0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
257d0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
257e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
257f0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
25800 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
25810 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
25820 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
25830 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
25840 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
25850 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
25860 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
25870 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
25880 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
25890 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
258a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
258b0 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55  re deprecated. U
258c0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
258d0 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65  trace_v2()] inte
258e0 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64  rface.** instead
258f0 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73   of the routines
25900 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e   described here.
25910 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
25920 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
25930 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
25940 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
25950 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
25960 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
25970 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
25980 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
25990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
259a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
259b0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
259c0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
259d0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
259e0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
259f0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
25a00 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
25a10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25a20 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
25a30 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
25a40 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
25a50 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
25a60 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
25a70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
25a80 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
25a90 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
25aa0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
25ab0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
25ac0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
25ad0 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
25ae0 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
25af0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
25b00 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
25b10 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
25b20 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
25b30 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
25b40 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
25b50 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
25b60 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
25b70 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
25b80 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
25b90 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
25ba0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
25bb0 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
25bc0 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
25bd0 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
25be0 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
25bf0 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
25c00 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
25c10 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
25c20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
25c30 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
25c40 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
25c50 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
25c60 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
25c70 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
25c80 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
25c90 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
25ca0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
25cb0 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
25cc0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
25cd0 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
25ce0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
25cf0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
25d00 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
25d10 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
25d20 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
25d30 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
25d40 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
25d50 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
25d60 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
25d70 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
25d80 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
25d90 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
25da0 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
25db0 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
25dc0 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
25dd0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
25de0 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
25df0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
25e00 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
25e10 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
25e20 63 6b 2e 20 20 49 6e 76 6f 6b 69 6e 67 0a 2a 2a  ck.  Invoking.**
25e30 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
25e40 5f 74 72 61 63 65 28 29 5d 20 6f 72 20 5b 73 71  _trace()] or [sq
25e50 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
25e60 5d 20 77 69 6c 6c 20 63 61 6e 63 65 6c 20 74 68  ] will cancel th
25e70 65 0a 2a 2a 20 70 72 6f 66 69 6c 65 20 63 61 6c  e.** profile cal
25e80 6c 62 61 63 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45  lback..*/.SQLITE
25e90 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
25ea0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
25eb0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
25ec0 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
25ed0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
25ee0 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  oid*);.SQLITE_DE
25ef0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
25f00 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
25f10 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
25f20 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
25f30 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
25f40 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
25f50 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
25f60 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63  PI3REF: SQL Trac
25f70 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a  e Event Codes.**
25f80 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
25f90 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68  E_TRACE.**.** Th
25fa0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64  ese constants id
25fb0 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f  entify classes o
25fc0 66 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61  f events that ca
25fd0 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a  n be monitored.*
25fe0 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  * using the [sql
25ff0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
26000 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20   tracing logic. 
26010 20 54 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a   The M argument.
26020 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ** to [sqlite3_t
26030 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29  race_v2(D,M,X,P)
26040 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f  ] is an OR-ed co
26050 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65  mbination of one
26060 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74   or more of.** t
26070 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
26080 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69  stants.  ^The fi
26090 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
260a0 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
260b0 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20  ck.** is one of 
260c0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
260d0 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e  nstants..**.** N
260e0 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74  ew tracing const
260f0 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65  ants may be adde
26100 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
26110 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  ases..**.** ^A t
26120 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61  race callback ha
26130 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  s four arguments
26140 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  : xCallback(T,C,
26150 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
26160 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
26170 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74  of the integer t
26180 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e  ype codes above.
26190 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d  .** ^The C argum
261a0 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ent is a copy of
261b0 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69   the context poi
261c0 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61  nter passed in a
261d0 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
261e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
261f0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
26200 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
26210 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
26220 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
26230 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
26240 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a   T..**.** <dl>.*
26250 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
26260 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49  _STMT]] <dt>SQLI
26270 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64  TE_TRACE_STMT</d
26280 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
26290 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
262a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
262b0 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61  ked when a prepa
262c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
262d0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75   first begins ru
262e0 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62  nning and possib
262f0 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65  ly at other time
26300 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  s during the.** 
26310 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
26320 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26330 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20  ent, such as at 
26340 74 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63  the start of eac
26350 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62  h.** trigger sub
26360 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20  program. ^The P 
26370 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
26380 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
26390 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
263a0 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67  ent]. ^The X arg
263b0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
263c0 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  er to a string w
263d0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75  hich.** is the u
263e0 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65  nexpanded SQL te
263f0 78 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  xt of the prepar
26400 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20  ed statement or 
26410 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a  an SQL comment .
26420 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
26430 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e  s the invocation
26440 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20   of a trigger.  
26450 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61  ^The callback ca
26460 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65  n compute.** the
26470 20 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20   same text that 
26480 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20  would have been 
26490 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
264a0 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
264b0 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65  trace()].** inte
264c0 72 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74  rface by using t
264d0 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68  he X argument wh
264e0 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68  en X begins with
264f0 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69   "--" and invoki
26500 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
26510 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20  xpanded_sql(P)] 
26520 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
26530 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
26540 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51  PROFILE]] <dt>SQ
26550 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
26560 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  LE</dt>.** <dd>^
26570 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
26580 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b  PROFILE callback
26590 20 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78   provides approx
265a0 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65  imately the same
265b0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
265c0 61 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  as is provided b
265d0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  y the [sqlite3_p
265e0 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61  rofile()] callba
265f0 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  ck..** ^The P ar
26600 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
26610 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70  ter to the [prep
26620 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26630 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67  and the.** X arg
26640 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20  ument points to 
26650 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  a 64-bit integer
26660 20 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73   which is the es
26670 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68  timated of.** th
26680 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
26690 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20  second that the 
266a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
266b0 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a  nt took to run..
266c0 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54  ** ^The SQLITE_T
266d0 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
266e0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
266f0 20 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   when the statem
26700 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
26710 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
26720 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c  CE_ROW]] <dt>SQL
26730 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64  ITE_TRACE_ROW</d
26740 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
26750 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63  LITE_TRACE_ROW c
26760 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
26770 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72  ed whenever a pr
26780 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
26790 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20  ent generates a 
267a0 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65  single row of re
267b0 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20  sult.  .** ^The 
267c0 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
267d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
267e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
267f0 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
26800 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
26810 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  sed..**.** [[SQL
26820 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d  ITE_TRACE_CLOSE]
26830 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
26840 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  CE_CLOSE</dt>.**
26850 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
26860 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c  TRACE_CLOSE call
26870 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
26880 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a  when a database.
26890 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  ** connection cl
268a0 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  oses..** ^The P 
268b0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
268c0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
268d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
268e0 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  n] object.** and
268f0 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
26900 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f  is unused..** </
26910 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
26920 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
26930 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66         0x01.#def
26940 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
26950 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32  _PROFILE    0x02
26960 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26970 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20  TRACE_ROW       
26980 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51   0x04.#define SQ
26990 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
269a0 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a        0x08../*.*
269b0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
269c0 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45  Trace Hook.** ME
269d0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
269e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
269f0 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c  _trace_v2(D,M,X,
26a00 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  P) interface reg
26a10 69 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63  isters a trace c
26a20 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
26a30 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64  ion X against [d
26a40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26a50 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f  on] D, using pro
26a60 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20  perty mask M.** 
26a70 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  and context poin
26a80 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20  ter P.  ^If the 
26a90 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a  X callback is.**
26aa0 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20   NULL or if the 
26ab0 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20  M mask is zero, 
26ac0 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20  then tracing is 
26ad0 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a  disabled.  The.*
26ae0 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  * M argument sho
26af0 75 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69  uld be the bitwi
26b00 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61  se OR-ed combina
26b10 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20  tion of.** zero 
26b20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f  or more [SQLITE_
26b30 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73  TRACE] constants
26b40 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61  ..**.** ^Each ca
26b50 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c  ll to either sql
26b60 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
26b70 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
26b80 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a  () overrides .**
26b90 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70   (cancels) any p
26ba0 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71  rior calls to sq
26bb0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72  lite3_trace() or
26bc0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
26bd0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  2()..**.** ^The 
26be0 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  X callback is in
26bf0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
26c00 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73  ny of the events
26c10 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a   identified by .
26c20 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e  ** mask M occur.
26c30 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72    ^The integer r
26c40 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
26c50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
26c60 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67   currently.** ig
26c70 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68  nored, though th
26c80 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e  is may change in
26c90 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
26ca0 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  .  Callback.** i
26cb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
26cc0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72  hould return zer
26cd0 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75  o to ensure futu
26ce0 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  re compatibility
26cf0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65  ..**.** ^A trace
26d00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
26d10 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61  oked with four a
26d20 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61  rguments: callba
26d30 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
26d40 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
26d50 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53  is one of the [S
26d60 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20  QLITE_TRACE].** 
26d70 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64  constants to ind
26d80 69 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61  icate why the ca
26d90 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b  llback was invok
26da0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72  ed..** ^The C ar
26db0 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79  gument is a copy
26dc0 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20   of the context 
26dd0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20  pointer..** The 
26de0 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
26df0 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
26e00 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
26e10 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
26e20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61   The sqlite3_tra
26e30 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  ce_v2() interfac
26e40 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  e is intended to
26e50 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67   replace the leg
26e60 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
26e70 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  s [sqlite3_trace
26e80 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26e90 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74  _profile()], bot
26ea0 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72  h of which.** ar
26eb0 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f  e deprecated..*/
26ec0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61  .int sqlite3_tra
26ed0 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ce_v2(.  sqlite3
26ee0 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d  *,.  unsigned uM
26ef0 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c  ask,.  int(*xCal
26f00 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c  lback)(unsigned,
26f10 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64  void*,void*,void
26f20 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78  *),.  void *pCtx
26f30 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
26f40 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
26f50 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
26f60 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
26f70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26f80 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
26f90 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
26fa0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
26fb0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
26fc0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
26fd0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
26fe0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
26ff0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
27000 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
27010 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
27020 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
27030 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
27040 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
27050 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
27060 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
27070 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
27080 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
27090 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
270a0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
270b0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
270c0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
270d0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
270e0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
270f0 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
27100 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
27110 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
27120 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
27130 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
27140 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
27150 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
27160 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
27170 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
27180 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
27190 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
271a0 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
271b0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
271c0 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
271d0 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
271e0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
271f0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
27200 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
27210 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
27220 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
27230 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
27240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
27250 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
27260 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
27270 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
27280 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
27290 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
272a0 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
272b0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
272c0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
272d0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
272e0 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
272f0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
27300 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
27310 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
27320 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
27330 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
27340 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
27350 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
27360 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
27370 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
27380 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
27390 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
273a0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
273b0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
273c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
273d0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
273e0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
273f0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
27400 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
27410 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
27420 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
27430 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
27440 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
27450 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
27460 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
27470 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
27480 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
27490 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
274a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
274b0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
274c0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
274d0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
274e0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
274f0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
27500 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
27510 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
27520 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
27530 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
27540 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
27550 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53  nnection.** CONS
27560 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
27570 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
27580 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
27590 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
275a0 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
275b0 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
275c0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
275d0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
275e0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
275f0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
27600 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
27610 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
27620 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
27630 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
27640 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
27650 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
27660 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
27670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27680 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
27690 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
276a0 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
276b0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
276c0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
276d0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
276e0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
276f0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
27700 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
27710 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
27720 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
27730 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
27740 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
27750 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
27760 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
27770 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
27780 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
27790 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
277a0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
277b0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
277c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
277d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
277e0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
277f0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
27800 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
27810 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
27820 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
27830 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
27840 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
27850 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
27860 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
27870 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
27880 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
27890 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
278a0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
278b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
278c0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
278d0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
278e0 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
278f0 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
27900 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
27910 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
27920 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
27930 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
27940 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
27950 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
27960 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
27970 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
27980 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
27990 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
279a0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
279b0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
279c0 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
279d0 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
279e0 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
279f0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
27a00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27a10 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
27a20 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
27a30 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
27a40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
27a50 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
27a60 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
27a70 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
27a80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
27a90 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
27aa0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
27ab0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
27ac0 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
27ad0 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
27ae0 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
27af0 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
27b00 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
27b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27b20 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
27b30 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
27b40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27b50 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
27b60 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
27b70 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
27b80 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
27b90 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
27ba0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
27bb0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
27bc0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
27bd0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
27be0 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
27bf0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
27c00 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
27c10 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
27c20 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
27c30 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
27c40 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
27c50 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
27c60 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
27c70 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
27c80 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
27c90 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
27ca0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
27cb0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
27cc0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
27cd0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
27ce0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
27cf0 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
27d00 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
27d10 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
27d20 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
27d30 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
27d40 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
27d50 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
27d60 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
27d70 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
27d80 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
27d90 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
27da0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
27db0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
27dc0 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
27dd0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
27de0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
27df0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
27e00 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
27e10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
27e20 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
27e30 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
27e40 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
27e50 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
27e60 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
27e70 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
27e80 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
27e90 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
27ea0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
27eb0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
27ec0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
27ed0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
27ee0 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
27ef0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
27f00 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
27f10 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
27f20 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
27f30 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
27f40 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
27f50 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
27f60 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
27f70 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
27f80 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
27f90 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
27fa0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
27fb0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
27fc0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
27fd0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
27fe0 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
27ff0 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
28000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28010 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
28020 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
28030 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
28040 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
28050 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
28060 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
28070 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
28080 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
28090 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
280a0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
280b0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
280c0 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
280d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
280e0 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
280f0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
28100 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
28110 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
28120 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
28130 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
28140 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
28150 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
28160 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
28170 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
28180 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
28190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
281a0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
281b0 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
281c0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
281d0 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
281e0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
281f0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
28200 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
28210 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
28220 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
28230 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
28240 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
28250 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
28260 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
28270 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
28280 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
28290 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
282a0 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
282b0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
282c0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
282d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
282e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
282f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28300 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
28310 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
28320 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
28330 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
28340 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
28350 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
28360 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
28370 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
28380 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
28390 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
283a0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
283b0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
283c0 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
283d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
283e0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
283f0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
28400 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
28410 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
28420 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
28430 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
28440 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
28450 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
28460 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
28470 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
28480 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
28490 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
284a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
284b0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
284c0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
284d0 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
284e0 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
284f0 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
28500 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
28510 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
28520 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
28530 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
28540 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
28550 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
28560 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
28570 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
28580 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
28590 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
285a0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
285b0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
285c0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
285d0 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
285e0 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
285f0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
28600 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
28610 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
28620 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
28630 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
28640 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
28650 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
28660 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
28670 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28680 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
28690 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
286a0 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
286b0 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
286c0 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
286d0 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
286e0 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
286f0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
28700 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
28710 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
28720 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
28730 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
28740 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
28750 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
28760 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
28770 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
28780 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
28790 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
287a0 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
287b0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72   in the third ar
287c0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
287d0 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
287e0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
287f0 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
28800 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
28810 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
28820 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
28830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
28840 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
28850 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
28860 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
28870 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
28880 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
28890 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
288a0 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
288b0 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
288c0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
288d0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
288e0 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
288f0 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
28900 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
28910 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
28920 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
28930 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
28940 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
28950 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
28960 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
28970 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
28980 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
28990 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
289a0 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
289b0 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
289c0 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
289d0 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
289e0 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
289f0 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
28a00 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
28a10 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
28a20 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
28a30 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
28a40 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
28a50 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
28a60 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
28a70 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
28a80 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
28a90 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
28aa0 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
28ab0 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
28ac0 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
28ad0 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
28ae0 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
28af0 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
28b00 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
28b10 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
28b20 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
28b30 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
28b40 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
28b50 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
28b60 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
28b70 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
28b80 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
28b90 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
28ba0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
28bb0 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
28bc0 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
28bd0 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
28be0 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
28bf0 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
28c00 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
28c10 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
28c20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
28c30 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
28c40 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
28c50 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
28c60 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
28c70 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
28c80 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
28c90 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
28ca0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
28cb0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
28cc0 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
28cd0 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
28ce0 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
28cf0 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
28d00 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
28d10 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
28d20 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
28d30 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
28d40 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
28d50 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
28d60 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
28d70 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
28d80 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
28d90 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
28da0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
28db0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
28dc0 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
28dd0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
28de0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
28df0 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
28e00 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
28e10 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
28e20 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
28e30 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
28e40 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
28e50 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
28e60 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
28e70 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
28e80 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
28e90 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
28ea0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
28eb0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
28ec0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
28ed0 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
28ee0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
28ef0 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
28f00 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
28f10 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
28f20 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
28f30 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
28f40 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
28f50 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
28f60 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
28f70 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
28f80 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
28f90 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
28fa0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
28fb0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
28fc0 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
28fd0 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
28fe0 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
28ff0 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
29000 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
29010 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
29020 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
29030 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
29040 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
29050 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
29060 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
29070 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
29080 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
29090 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
290a0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
290b0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
290c0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
290d0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
290e0 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
290f0 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
29100 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
29110 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
29120 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
29130 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
29140 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
29150 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
29160 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
29170 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
29180 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
29190 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
291a0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
291b0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
291c0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
291d0 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
291e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
291f0 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
29200 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
29210 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
29220 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
29230 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
29240 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
29250 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
29260 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
29270 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
29280 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
29290 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
292a0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
292b0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
292c0 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
292d0 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
292e0 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
292f0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
29300 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
29310 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
29320 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
29330 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
29340 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
29350 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
29360 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
29370 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
29380 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
29390 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
293a0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
293b0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
293c0 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
293d0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
293e0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
293f0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
29400 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
29410 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
29420 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
29430 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
29440 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
29450 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
29460 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
29470 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
29480 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
29490 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
294a0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
294b0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
294c0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
294d0 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
294e0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
294f0 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
29500 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
29510 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
29520 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
29530 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
29540 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
29550 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
29560 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
29570 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
29580 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
29590 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
295a0 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
295b0 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
295c0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
295d0 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
295e0 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
295f0 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
29600 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
29610 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
29620 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
29630 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
29640 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
29650 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
29660 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
29670 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
29680 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
29690 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
296a0 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
296b0 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
296c0 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
296d0 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
296e0 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
296f0 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
29700 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
29710 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
29720 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
29730 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
29740 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
29750 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
29760 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
29770 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
29780 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
29790 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
297a0 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
297b0 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
297c0 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
297d0 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
297e0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
297f0 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
29800 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
29810 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
29820 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
29830 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
29840 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
29850 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
29860 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
29870 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
29880 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
29890 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
298a0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
298b0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
298c0 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
298d0 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
298e0 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
298f0 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
29900 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
29910 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
29920 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
29930 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
29940 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
29950 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
29960 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
29970 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
29980 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
29990 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
299a0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
299b0 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
299c0 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
299d0 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
299e0 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
299f0 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
29a00 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
29a10 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
29a20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
29a30 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
29a40 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
29a50 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
29a60 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
29a70 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
29a80 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
29a90 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
29aa0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
29ab0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
29ac0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
29ad0 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
29ae0 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
29af0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
29b00 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
29b10 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
29b20 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
29b30 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
29b40 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
29b50 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
29b60 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
29b70 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
29b80 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
29b90 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
29ba0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
29bb0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
29bc0 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
29bd0 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
29be0 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
29bf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
29c00 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
29c10 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
29c20 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
29c30 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
29c40 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
29c50 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
29c60 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
29c70 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
29c80 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
29c90 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
29ca0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
29cb0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
29cc0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
29cd0 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
29ce0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
29cf0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
29d00 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
29d10 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
29d20 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
29d30 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
29d40 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
29d50 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
29d60 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
29d70 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
29d80 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
29d90 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
29da0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
29db0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
29dc0 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
29dd0 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
29de0 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
29df0 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
29e00 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
29e10 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
29e20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
29e30 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
29e40 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
29e50 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
29e60 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
29e70 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
29e80 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
29e90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
29ea0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
29eb0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
29ec0 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
29ed0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
29ee0 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
29ef0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
29f00 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
29f10 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
29f20 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
29f30 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
29f40 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
29f50 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
29f60 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
29f70 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
29f80 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
29f90 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
29fa0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
29fb0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
29fc0 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
29fd0 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
29fe0 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
29ff0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
2a000 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
2a010 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
2a020 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
2a030 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
2a040 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
2a050 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
2a060 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
2a070 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
2a080 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
2a090 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
2a0a0 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
2a0b0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
2a0c0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
2a0d0 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
2a0e0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
2a0f0 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
2a100 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
2a110 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
2a120 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
2a130 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
2a140 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
2a150 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
2a160 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
2a170 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
2a180 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
2a190 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
2a1a0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
2a1b0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
2a1c0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
2a1d0 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
2a1e0 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
2a1f0 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
2a200 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
2a210 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
2a220 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
2a230 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
2a240 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
2a250 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
2a260 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
2a270 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
2a280 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
2a290 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
2a2a0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
2a2b0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
2a2c0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
2a2d0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
2a2e0 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
2a2f0 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
2a300 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
2a310 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
2a320 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
2a330 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
2a340 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
2a350 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2a360 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
2a370 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
2a380 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
2a390 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
2a3a0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
2a3b0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
2a3c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
2a3d0 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
2a3e0 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
2a3f0 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
2a400 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
2a410 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
2a420 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
2a430 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
2a440 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
2a450 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
2a460 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
2a470 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
2a480 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
2a490 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
2a4a0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
2a4b0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
2a4c0 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
2a4d0 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
2a4e0 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
2a4f0 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
2a500 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
2a510 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
2a520 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
2a530 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
2a540 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
2a550 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
2a560 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
2a570 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
2a580 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
2a590 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
2a5a0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
2a5b0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
2a5c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
2a5d0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
2a5e0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
2a5f0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
2a600 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
2a610 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
2a620 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
2a630 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2a640 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
2a650 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
2a660 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
2a670 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
2a680 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
2a690 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
2a6a0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
2a6b0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
2a6c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2a6d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
2a6e0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
2a6f0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
2a700 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
2a710 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
2a720 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
2a730 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
2a740 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
2a750 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
2a760 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
2a770 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
2a780 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
2a790 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
2a7a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2a7b0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
2a7c0 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
2a7d0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
2a7e0 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
2a7f0 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
2a800 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
2a810 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
2a820 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
2a830 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
2a840 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
2a850 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
2a860 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
2a870 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
2a880 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
2a890 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
2a8a0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
2a8b0 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
2a8c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
2a8d0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
2a8e0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
2a8f0 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
2a900 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
2a910 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
2a920 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
2a930 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
2a940 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
2a950 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
2a960 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
2a970 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
2a980 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
2a990 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2a9a0 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
2a9b0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
2a9c0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
2a9d0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
2a9e0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2a9f0 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
2aa00 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
2aa10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
2aa20 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
2aa30 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
2aa40 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
2aa50 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
2aa60 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
2aa70 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
2aa80 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
2aa90 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
2aaa0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
2aab0 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
2aac0 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
2aad0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
2aae0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
2aaf0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
2ab00 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
2ab10 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
2ab20 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
2ab30 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
2ab40 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
2ab50 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
2ab60 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
2ab70 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
2ab80 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
2ab90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
2aba0 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
2abb0 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
2abc0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
2abd0 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
2abe0 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
2abf0 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
2ac00 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
2ac10 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
2ac20 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
2ac30 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
2ac40 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
2ac50 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
2ac60 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
2ac70 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
2ac80 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
2ac90 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
2aca0 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
2acb0 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
2acc0 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
2acd0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
2ace0 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
2acf0 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
2ad00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
2ad10 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
2ad20 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
2ad30 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
2ad40 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
2ad50 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
2ad60 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
2ad70 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
2ad80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ad90 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
2ada0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
2adb0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
2adc0 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
2add0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2ade0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
2adf0 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
2ae00 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
2ae10 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
2ae20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
2ae30 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2ae40 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
2ae50 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
2ae60 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
2ae70 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
2ae80 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
2ae90 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
2aea0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
2aeb0 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
2aec0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
2aed0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
2aee0 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
2aef0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
2af00 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
2af10 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
2af20 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
2af30 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
2af40 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
2af50 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
2af60 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2af70 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
2af80 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2af90 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
2afa0 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
2afb0 53 65 65 20 74 68 65 20 5b 55 52 49 20 66 69 6c  See the [URI fil
2afc0 65 6e 61 6d 65 5d 20 64 6f 63 75 6d 65 6e 74 61  ename] documenta
2afd0 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
2afe0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2aff0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2b000 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
2b010 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
2b020 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
2b030 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
2b040 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  ;.int sqlite3_ur
2b050 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
2b060 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
2b070 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
2b080 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
2b090 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2b0a0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
2b0b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
2b0c0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2b0d0 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
2b0e0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
2b0f0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
2b100 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ages.** METHOD: 
2b110 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49  sqlite3.**.** ^I
2b120 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2b130 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  t sqlite3_* API 
2b140 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
2b150 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61  with .** [databa
2b160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2b170 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68   failed, then th
2b180 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
2b190 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  e(D) interface.*
2b1a0 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * returns the nu
2b1b0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
2b1c0 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
2b1d0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
2b1e0 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61  r that.** API ca
2b1f0 6c 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ll..** ^The sqli
2b200 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
2b210 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
2b220 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
2b230 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
2b240 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
2b250 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
2b260 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
2b270 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
2b280 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
2b290 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
2b2a0 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 72  .** The values r
2b2b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2b2c0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 61 6e 64  e3_errcode() and
2b2d0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  /or.** sqlite3_e
2b2e0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
2b2f0 29 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 77  ) might change w
2b300 69 74 68 20 65 61 63 68 20 41 50 49 20 63 61 6c  ith each API cal
2b310 6c 2e 0a 2a 2a 20 45 78 63 65 70 74 2c 20 74 68  l..** Except, th
2b320 65 72 65 20 61 72 65 20 73 6f 6d 65 20 69 6e 74  ere are some int
2b330 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65  erfaces that are
2b340 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 6e   guaranteed to n
2b350 65 76 65 72 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ever.** change t
2b360 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2b370 65 72 72 6f 72 20 63 6f 64 65 2e 20 20 54 68 65  error code.  The
2b380 20 65 72 72 6f 72 2d 63 6f 64 65 20 70 72 65 73   error-code pres
2b390 65 72 76 69 6e 67 0a 2a 2a 20 69 6e 74 65 72 66  erving.** interf
2b3a0 61 63 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a 20  aces are:.**.** 
2b3b0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  <ul>.** <li> sql
2b3c0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
2b3d0 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65  * <li> sqlite3_e
2b3e0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
2b3f0 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  ).** <li> sqlite
2b400 33 5f 65 72 72 6d 73 67 28 29 0a 2a 2a 20 3c 6c  3_errmsg().** <l
2b410 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  i> sqlite3_errms
2b420 67 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  g16().** </ul>.*
2b430 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b440 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
2b450 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
2b460 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
2b470 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
2b480 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
2b490 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
2b4a0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2b4b0 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
2b4c0 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
2b4d0 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
2b4e0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
2b4f0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
2b500 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
2b510 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
2b520 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
2b530 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
2b540 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
2b550 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
2b560 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
2b570 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
2b580 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
2b590 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
2b5a0 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
2b5b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
2b5c0 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
2b5d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
2b5e0 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
2b5f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
2b600 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
2b610 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
2b620 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
2b630 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
2b640 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
2b650 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
2b660 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
2b670 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
2b680 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
2b690 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
2b6a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b6b0 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
2b6c0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
2b6d0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
2b6e0 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
2b6f0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
2b700 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
2b710 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
2b720 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
2b730 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
2b740 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
2b750 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
2b760 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
2b770 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
2b780 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
2b790 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
2b7a0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
2b7b0 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
2b7c0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
2b7d0 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
2b7e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
2b7f0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
2b800 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
2b810 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
2b820 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
2b830 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2b840 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
2b850 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
2b860 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
2b870 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
2b880 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
2b890 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
2b8a0 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
2b8b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
2b8c0 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
2b8d0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
2b8e0 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
2b8f0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
2b900 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
2b910 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
2b920 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
2b930 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
2b940 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
2b950 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
2b960 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
2b970 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
2b980 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
2b990 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
2b9a0 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
2b9b0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
2b9c0 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
2b9d0 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
2b9e0 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
2b9f0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
2ba00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
2ba10 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
2ba20 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
2ba30 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ba40 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
2ba50 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2ba60 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
2ba70 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
2ba80 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
2ba90 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
2baa0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70  * CAPI3REF: Prep
2bab0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2bac0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2bad0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
2bae0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
2baf0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
2bb00 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
2bb10 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
2bb20 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
2bb30 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
2bb40 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65   that.** has bee
2bb50 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  n compiled into 
2bb60 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20  binary form and 
2bb70 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65  is ready to be e
2bb80 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  valuated..**.** 
2bb90 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51  Think of each SQ
2bba0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61  L statement as a
2bbb0 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74   separate comput
2bbc0 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65  er program.  The
2bbd0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2bbe0 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20   text is source 
2bbf0 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65  code.  A prepare
2bc00 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
2bc10 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f  ct .** is the co
2bc20 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f  mpiled object co
2bc30 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73  de.  All SQL mus
2bc40 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69  t be converted i
2bc50 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65  nto a.** prepare
2bc60 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f  d statement befo
2bc70 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e  re it can be run
2bc80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
2bc90 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70  -cycle of a prep
2bca0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
2bcb0 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f  bject usually go
2bcc0 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  es like this:.**
2bcd0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2bce0 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70   Create the prep
2bcf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
2bd00 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
2bd10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2bd20 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  )]..** <li> Bind
2bd30 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61   values to [para
2bd40 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
2bd50 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2bd60 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
2bd70 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
2bd80 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
2bd90 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
2bda0 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
2bdb0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
2bdc0 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70  > Reset the prep
2bdd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2bde0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
2bdf0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
2be00 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
2be10 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
2be20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
2be30 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
2be40 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
2be50 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2be60 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
2be70 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ol>.*/.typedef s
2be80 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
2be90 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
2bea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2beb0 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
2bec0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
2bed0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ite3.**.** ^(Thi
2bee0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
2bef0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
2bf00 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
2bf10 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
2bf20 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
2bf30 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
2bf40 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
2bf50 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2bf60 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
2bf70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
2bf80 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
2bf90 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
2bfa0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
2bfb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
2bfc0 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
2bfd0 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
2bfe0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
2bff0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
2c000 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
2c010 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
2c020 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2c030 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
2c040 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
2c050 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
2c060 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
2c070 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
2c080 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
2c090 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
2c0a0 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
2c0b0 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
2c0c0 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
2c0d0 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
2c0e0 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
2c0f0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
2c100 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
2c110 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
2c120 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
2c130 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
2c140 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
2c150 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
2c160 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
2c170 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
2c180 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
2c190 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
2c1a0 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
2c1b0 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
2c1c0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
2c1d0 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
2c1e0 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
2c1f0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
2c200 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
2c210 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2c220 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
2c230 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
2c240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
2c250 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
2c260 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
2c270 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
2c280 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
2c290 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
2c2a0 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
2c2b0 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
2c2c0 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
2c2d0 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
2c2e0 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
2c2f0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2c300 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
2c310 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
2c320 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
2c330 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
2c340 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
2c350 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
2c360 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
2c370 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
2c380 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
2c390 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
2c3a0 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
2c3b0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
2c3c0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
2c3d0 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
2c3e0 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
2c3f0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
2c400 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
2c410 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
2c420 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
2c430 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
2c440 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
2c450 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
2c460 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
2c470 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
2c480 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
2c490 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
2c4a0 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
2c4b0 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
2c4c0 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
2c4d0 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
2c4e0 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
2c4f0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
2c500 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
2c510 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
2c520 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
2c530 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
2c540 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
2c550 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
2c560 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
2c570 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
2c580 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
2c590 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
2c5a0 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
2c5b0 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
2c5c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
2c5d0 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
2c5e0 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
2c5f0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
2c600 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
2c610 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
2c620 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
2c630 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
2c640 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
2c650 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
2c660 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
2c670 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
2c680 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
2c690 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
2c6a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c6b0 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
2c6c0 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
2c6d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
2c6e0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
2c6f0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
2c700 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2c710 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
2c720 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
2c730 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
2c740 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
2c750 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
2c760 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
2c770 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
2c780 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
2c790 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
2c7a0 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
2c7b0 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
2c7c0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2c7d0 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
2c7e0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
2c7f0 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
2c800 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
2c810 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2c820 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
2c830 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2c840 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2c850 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
2c860 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
2c870 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
2c880 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
2c890 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2c8a0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2c8b0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2c8c0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2c8d0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2c8e0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
2c8f0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
2c900 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
2c910 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2c920 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
2c930 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
2c940 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
2c950 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2c960 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2c970 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
2c980 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
2c990 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
2c9a0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2c9b0 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
2c9c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
2c9d0 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
2c9e0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
2c9f0 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
2ca00 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
2ca10 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2ca20 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2ca30 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2ca40 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2ca50 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2ca60 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
2ca70 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
2ca80 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
2ca90 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
2caa0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2cab0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
2cac0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2cad0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
2cae0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
2caf0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2cb00 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
2cb10 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
2cb20 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
2cb30 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2cb40 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2cb50 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
2cb60 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
2cb70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2cb80 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2cb90 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
2cba0 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
2cbb0 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
2cbc0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
2cbd0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2cbe0 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70  .  If [sqlite3_p
2cbf0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
2cc00 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  ** the equivalen
2cc10 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63  t tries to alloc
2cc20 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f  ate space for mo
2cc30 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e  re than this man
2cc40 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20  y opcodes.** in 
2cc50 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65  a single prepare
2cc60 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20  d statement, an 
2cc70 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72  SQLITE_NOMEM err
2cc80 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
2cc90 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2cca0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2ccb0 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
2ccc0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
2ccd0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
2cce0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2ccf0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
2cd00 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
2cd10 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
2cd20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2cd30 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
2cd40 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2cd50 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
2cd60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2cd70 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
2cd80 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
2cd90 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
2cda0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2cdb0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2cdc0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
2cdd0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2cde0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
2cdf0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
2ce00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
2ce10 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
2ce20 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
2ce30 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
2ce40 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2ce50 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2ce60 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
2ce70 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
2ce80 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
2ce90 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2cea0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
2ceb0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
2cec0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
2ced0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
2cee0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
2cef0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
2cf00 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2cf10 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
2cf20 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
2cf30 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
2cf40 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2cf50 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
2cf60 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
2cf70 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
2cf80 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2cf90 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
2cfa0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2cfb0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2cfc0 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
2cfd0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2cfe0 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
2cff0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
2d000 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
2d010 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d020 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
2d030 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
2d040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d050 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
2d060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d070 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
2d080 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2d090 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
2d0a0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2d0b0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2d0c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d0d0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2d0e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2d0f0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2d100 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2d110 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2d120 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
2d130 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
2d140 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2d150 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
2d160 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
2d170 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
2d180 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
2d190 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
2d1a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
2d1b0 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
2d1c0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
2d1d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2d1e0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2d1f0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
2d200 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2d210 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2d220 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
2d230 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2d240 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
2d250 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
2d260 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2d270 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2d280 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
2d290 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d2a0 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a  Prepare Flags.**
2d2b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2d2c0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
2d2d0 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63 61  us flags that ca
2d2e0 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f  n be passed into
2d2f0 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20  .** "prepFlags" 
2d300 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2d310 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d320 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  e_v3()] and.** [
2d330 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d340 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63  6_v3()] interfac
2d350 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c  es..**.** New fl
2d360 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ags may be added
2d370 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
2d380 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
2d390 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
2d3a0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2d3b0 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74  RSISTENT]] ^(<dt
2d3c0 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  >SQLITE_PREPARE_
2d3d0 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a  PERSISTENT</dt>.
2d3e0 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
2d3f0 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2d400 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68  TENT flag is a h
2d410 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72 79  int to the query
2d420 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74   planner.** that
2d430 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2d440 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
2d450 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c  retained for a l
2d460 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20  ong time and.** 
2d470 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20  probably reused 
2d480 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57  many times.)^ ^W
2d490 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67  ithout this flag
2d4a0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
2d4b0 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20  re_v3()].** and 
2d4c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d4d0 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20  16_v3()] assume 
2d4e0 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
2d4f0 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  d statement will
2d500 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73   .** be used jus
2d510 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73  t once or at mos
2d520 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e  t a few times an
2d530 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64  d then destroyed
2d540 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2d550 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72  e3_finalize()] r
2d560 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20  elatively soon. 
2d570 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  The current impl
2d580 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a  ementation acts.
2d590 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ** on this hint 
2d5a0 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20  by avoiding the 
2d5b0 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64  use of [lookasid
2d5c0 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20  e memory] so as 
2d5d0 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74  not to.** deplet
2d5e0 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74  e the limited st
2d5f0 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ore of lookaside
2d600 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20   memory. Future 
2d610 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53  versions of.** S
2d620 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e  QLite may act on
2d630 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 66 65   this hint diffe
2d640 72 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  rently..**.** [[
2d650 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2d660 4f 52 4d 41 4c 49 5a 45 5d 5d 20 3c 64 74 3e 53  ORMALIZE]] <dt>S
2d670 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f  QLITE_PREPARE_NO
2d680 52 4d 41 4c 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20  RMALIZE</dt>.** 
2d690 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50  <dd>The SQLITE_P
2d6a0 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45  REPARE_NORMALIZE
2d6b0 20 66 6c 61 67 20 69 73 20 61 20 6e 6f 2d 6f 70   flag is a no-op
2d6c0 2e 20 54 68 69 73 20 66 6c 61 67 20 75 73 65 64  . This flag used
2d6d0 0a 2a 2a 20 74 6f 20 62 65 20 72 65 71 75 69 72  .** to be requir
2d6e0 65 64 20 66 6f 72 20 61 6e 79 20 70 72 65 70 61  ed for any prepa
2d6f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 68  red statement th
2d700 61 74 20 77 61 6e 74 65 64 20 74 6f 20 75 73 65  at wanted to use
2d710 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2d720 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2d730 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 48  )] interface.  H
2d740 6f 77 65 76 65 72 2c 20 74 68 65 0a 2a 2a 20 5b  owever, the.** [
2d750 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a  sqlite3_normaliz
2d760 65 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72 66  ed_sql()] interf
2d770 61 63 65 20 69 73 20 6e 6f 77 20 61 76 61 69 6c  ace is now avail
2d780 61 62 6c 65 20 74 6f 20 61 6c 6c 0a 2a 2a 20 70  able to all.** p
2d790 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d7a0 74 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ts, regardless o
2d7b0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2d7c0 20 74 68 65 79 20 75 73 65 20 74 68 69 73 0a 2a   they use this.*
2d7d0 2a 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  * flag..**.** [[
2d7e0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2d7f0 4f 5f 56 54 41 42 5d 5d 20 3c 64 74 3e 53 51 4c  O_VTAB]] <dt>SQL
2d800 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56  ITE_PREPARE_NO_V
2d810 54 41 42 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TAB</dt>.** <dd>
2d820 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  The SQLITE_PREPA
2d830 52 45 5f 4e 4f 5f 56 54 41 42 20 66 6c 61 67 20  RE_NO_VTAB flag 
2d840 63 61 75 73 65 73 20 74 68 65 20 53 51 4c 20 63  causes the SQL c
2d850 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 72 65  ompiler.** to re
2d860 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 28 65  turn an error (e
2d870 72 72 6f 72 20 63 6f 64 65 20 53 51 4c 49 54 45  rror code SQLITE
2d880 5f 45 52 52 4f 52 29 20 69 66 20 74 68 65 20 73  _ERROR) if the s
2d890 74 61 74 65 6d 65 6e 74 20 75 73 65 73 0a 2a 2a  tatement uses.**
2d8a0 20 61 6e 79 20 76 69 72 74 75 61 6c 20 74 61 62   any virtual tab
2d8b0 6c 65 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  les..** </dl>.*/
2d8c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d8d0 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2d8e0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
2d8f0 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
2d900 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d  ITE_PREPARE_NORM
2d910 41 4c 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALIZE           
2d920 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65      0x02.#define
2d930 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2d940 4e 4f 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NO_VTAB         
2d950 20 20 20 20 20 20 20 20 30 78 30 34 0a 0a 2f 2a          0x04../*
2d960 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2d970 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
2d980 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
2d990 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
2d9a0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
2d9b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2d9c0 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  3.** CONSTRUCTOR
2d9d0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d9e0 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
2d9f0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2da00 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
2da10 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
2da20 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
2da30 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
2da40 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2da50 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68  nes.  Or, in oth
2da60 65 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20  er words, these 
2da70 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2da80 63 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72  constructors for
2da90 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2daa0 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
2dab0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66  ..**.** The pref
2dac0 65 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f  erred routine to
2dad0 20 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33   use is [sqlite3
2dae0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20  _prepare_v2()]. 
2daf0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
2db00 5f 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65  _prepare()] inte
2db10 72 66 61 63 65 20 69 73 20 6c 65 67 61 63 79 20  rface is legacy 
2db20 61 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76  and should be av
2db30 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74  oided..** [sqlit
2db40 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2db50 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 22 70   has an extra "p
2db60 72 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e  repFlags" option
2db70 20 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a   that is used.**
2db80 20 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72   for special pur
2db90 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  poses..**.** The
2dba0 20 75 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d   use of the UTF-
2dbb0 38 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  8 interfaces is 
2dbc0 70 72 65 66 65 72 72 65 64 2c 20 61 73 20 53 51  preferred, as SQ
2dbd0 4c 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a  Lite currently.*
2dbe0 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69  * does all parsi
2dbf0 6e 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20  ng using UTF-8. 
2dc00 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65   The UTF-16 inte
2dc10 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
2dc20 64 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76  ded.** as a conv
2dc30 65 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54  enience.  The UT
2dc40 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20  F-16 interfaces 
2dc50 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69  work by converti
2dc60 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20  ng the.** input 
2dc70 74 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c  text into UTF-8,
2dc80 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74   then invoking t
2dc90 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2dca0 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65   UTF-8 interface
2dcb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2dcc0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
2dcd0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
2dce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
2dcf0 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
2dd00 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
2dd10 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2dd20 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2dd30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
2dd40 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
2dd50 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
2dd60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2dd70 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
2dd80 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
2dd90 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
2dda0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
2ddb0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
2ddc0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
2ddd0 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
2dde0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2ddf0 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
2de00 74 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73  te3_prepare(), s
2de10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2de20 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  2(),.** and sqli
2de30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2de40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
2de50 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
2de60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2de70 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2de80 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  re16_v2(),.** an
2de90 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2dea0 65 31 36 5f 76 33 28 29 20 75 73 65 20 55 54 46  e16_v3() use UTF
2deb0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
2dec0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
2ded0 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
2dee0 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
2def0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
2df00 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2df10 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
2df20 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
2df30 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
2df40 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
2df50 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
2df60 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
2df70 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
2df80 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2df90 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
2dfa0 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
2dfb0 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
2dfc0 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
2dfd0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
2dfe0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
2dff0 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
2e000 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
2e010 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
2e020 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
2e030 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
2e040 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2e050 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
2e060 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
2e070 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
2e080 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
2e090 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
2e0a0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
2e0b0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
2e0c0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
2e0d0 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
2e0e0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
2e0f0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
2e100 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
2e110 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
2e120 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
2e130 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
2e140 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
2e150 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
2e160 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
2e170 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
2e180 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
2e190 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2e1a0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
2e1b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e1c0 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
2e1d0 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
2e1e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
2e1f0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
2e200 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
2e210 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
2e220 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
2e230 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
2e240 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
2e250 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
2e260 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
2e270 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
2e280 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
2e290 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
2e2a0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
2e2b0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
2e2c0 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
2e2d0 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
2e2e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
2e2f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2e300 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
2e310 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
2e320 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
2e330 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
2e340 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
2e350 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
2e360 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
2e370 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
2e380 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2e390 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
2e3a0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2e3b0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2e3c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
2e3d0 72 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c  repare_v2(), sql
2e3e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2e3f0 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2e400 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  re16_v2(),.** an
2e410 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2e420 65 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61  e16_v3() interfa
2e430 63 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e  ces are recommen
2e440 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
2e450 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65  programs..** The
2e460 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
2e470 73 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s (sqlite3_prepa
2e480 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
2e490 5f 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a  _prepare16()).**
2e4a0 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
2e4b0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
2e4c0 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
2e4d0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
2e4e0 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
2e4f0 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61  the "vX" interfa
2e500 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
2e510 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
2e520 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
2e530 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2e540 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
2e550 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
2e560 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
2e570 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
2e580 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
2e590 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
2e5a0 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
2e5b0 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
2e5c0 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
2e5d0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
2e5e0 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2e5f0 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
2e600 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
2e610 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2e620 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
2e630 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
2e640 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
2e650 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
2e660 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2e670 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
2e680 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
2e690 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
2e6a0 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
2e6b0 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
2e6c0 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
2e6d0 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
2e6e0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2e6f0 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
2e700 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
2e710 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2e720 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
2e730 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
2e740 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2e750 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
2e760 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
2e770 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
2e780 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
2e790 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
2e7a0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
2e7b0 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
2e7c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
2e7d0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
2e7e0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
2e7f0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
2e800 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
2e810 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
2e820 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
2e830 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
2e840 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e850 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
2e860 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
2e870 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
2e880 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
2e890 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
2e8a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
2e8b0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
2e8c0 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
2e8d0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
2e8e0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
2e8f0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
2e900 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
2e910 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
2e920 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
2e930 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
2e940 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
2e950 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
2e960 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
2e970 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2e980 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
2e990 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
2e9a0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2e9b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2e9c0 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
2e9d0 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
2e9e0 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
2e9f0 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
2ea00 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
2ea10 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
2ea20 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
2ea30 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2ea40 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
2ea50 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
2ea60 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
2ea70 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
2ea80 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
2ea90 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
2eaa0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2eab0 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
2eac0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
2ead0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2eae0 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
2eaf0 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
2eb00 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
2eb10 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
2eb20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
2eb30 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
2eb40 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
2eb50 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
2eb60 41 42 4c 45 5f 53 54 41 54 34 5d 20 63 6f 6d 70  ABLE_STAT4] comp
2eb70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2eb80 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c  is enabled..** <
2eb90 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  /li>.** </ol>.**
2eba0 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f  .** <p>^sqlite3_
2ebb0 70 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66  prepare_v3() dif
2ebc0 66 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  fers from sqlite
2ebd0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f  3_prepare_v2() o
2ebe0 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a  nly in having.**
2ebf0 20 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46   the extra prepF
2ec00 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20  lags parameter, 
2ec10 77 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61  which is a bit a
2ec20 72 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20  rray consisting 
2ec30 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f  of zero or.** mo
2ec40 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
2ec50 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2ec60 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50  TENT|SQLITE_PREP
2ec70 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e  ARE_*] flags.  ^
2ec80 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
2ec90 72 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65  repare_v2() inte
2eca0 72 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63  rface works exac
2ecb0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a  tly the same as.
2ecc0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
2ecd0 72 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a  re_v3() with a z
2ece0 65 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61  ero prepFlags pa
2ecf0 72 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20  rameter..*/.int 
2ed00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2ed10 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2ed20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2ed30 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2ed40 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2ed50 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2ed60 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2ed70 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2ed80 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2ed90 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2eda0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2edb0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2edc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2edd0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2ede0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2edf0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2ee00 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2ee10 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2ee20 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2ee30 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2ee40 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2ee50 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2ee60 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2ee70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2ee80 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2ee90 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2eea0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2eeb0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2eec0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2eed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2eee0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2eef0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2ef00 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2ef10 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2ef20 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2ef30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ef40 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2ef50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2ef60 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2ef70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2ef80 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2ef90 5f 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73  _prepare_v3(.  s
2efa0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2efb0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2efc0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2efd0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2efe0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2eff0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2f000 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2f010 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2f020 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2f030 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2f040 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73   bytes. */.  uns
2f050 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c  igned int prepFl
2f060 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20  ags, /* Zero or 
2f070 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50  more SQLITE_PREP
2f080 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20  ARE_ flags */.  
2f090 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2f0a0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2f0b0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2f0c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2f0d0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2f0e0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2f0f0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2f100 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2f110 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2f120 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
2f130 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2f140 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2f150 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2f160 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2f170 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2f180 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2f190 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2f1a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2f1b0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2f1c0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2f1d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2f1e0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2f1f0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2f200 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2f210 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2f220 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2f230 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2f240 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2f250 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2f260 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
2f270 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2f280 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2f290 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2f2a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2f2b0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2f2c0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2f2d0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2f2e0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2f2f0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2f300 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2f310 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2f320 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2f330 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2f340 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2f350 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2f360 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2f370 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2f380 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2f390 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2f3a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2f3b0 31 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33  16_v3(.  sqlite3
2f3c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2f3d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2f3e0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2f3f0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2f400 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2f410 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2f420 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2f430 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2f440 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2f450 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2f460 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64  s. */.  unsigned
2f470 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20   int prepFlags, 
2f480 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  /* Zero or more 
2f490 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20  SQLITE_PREPARE_ 
2f4a0 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74  flags */.  sqlit
2f4b0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2f4c0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2f4d0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2f4e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2f4f0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2f500 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2f510 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2f520 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
2f530 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
2f540 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
2f550 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  QL.** METHOD: sq
2f560 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f570 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71   ^The sqlite3_sq
2f580 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  l(P) interface r
2f590 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2f5a0 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68   to a copy of th
2f5b0 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74  e UTF-8.** SQL t
2f5c0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
2f5d0 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  te [prepared sta
2f5e0 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77  tement] P if P w
2f5f0 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  as.** created by
2f600 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f610 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2f620 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
2f630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2f640 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72  pare16_v2()], or
2f650 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f660 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54  e16_v3()]..** ^T
2f670 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  he sqlite3_expan
2f680 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  ded_sql(P) inter
2f690 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2f6a0 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d  ointer to a UTF-
2f6b0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  8.** string cont
2f6c0 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74  aining the SQL t
2f6d0 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20  ext of prepared 
2f6e0 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68  statement P with
2f6f0 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d  .** [bound param
2f700 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e  eters] expanded.
2f710 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f720 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2f730 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2f740 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2f750 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2f760 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2f770 68 65 20 6e 6f 72 6d 61 6c 69 7a 65 64 20 53 51  he normalized SQ
2f780 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72  L text of prepar
2f790 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 2e 20  ed statement P. 
2f7a0 20 54 68 65 0a 2a 2a 20 73 65 6d 61 6e 74 69 63   The.** semantic
2f7b0 73 20 75 73 65 64 20 74 6f 20 6e 6f 72 6d 61 6c  s used to normal
2f7c0 69 7a 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d  ize a SQL statem
2f7d0 65 6e 74 20 61 72 65 20 75 6e 73 70 65 63 69 66  ent are unspecif
2f7e0 69 65 64 20 61 6e 64 20 73 75 62 6a 65 63 74 0a  ied and subject.
2f7f0 2a 2a 20 74 6f 20 63 68 61 6e 67 65 2e 20 20 41  ** to change.  A
2f800 74 20 61 20 6d 69 6e 69 6d 75 6d 2c 20 6c 69 74  t a minimum, lit
2f810 65 72 61 6c 20 76 61 6c 75 65 73 20 77 69 6c 6c  eral values will
2f820 20 62 65 20 72 65 70 6c 61 63 65 64 20 77 69 74   be replaced wit
2f830 68 20 73 75 69 74 61 62 6c 65 0a 2a 2a 20 70 6c  h suitable.** pl
2f840 61 63 65 68 6f 6c 64 65 72 73 2e 0a 2a 2a 0a 2a  aceholders..**.*
2f850 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2f860 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20 73   if a prepared s
2f870 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61  tatement is crea
2f880 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ted using the SQ
2f890 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43  L.** text "SELEC
2f8a0 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64  T $abc,:xyz" and
2f8b0 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24 61   if parameter $a
2f8c0 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69  bc is bound to i
2f8d0 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61  nteger 2345.** a
2f8e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79  nd parameter :xy
2f8f0 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68  z is unbound, th
2f900 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  en sqlite3_sql()
2f910 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2f920 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72  the original str
2f930 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62  ing, "SELECT $ab
2f940 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69  c,:xyz" but sqli
2f950 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2f960 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  ().** will retur
2f970 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e  n "SELECT 2345,N
2f980 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ULL".)^.**.** ^T
2f990 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  he sqlite3_expan
2f9a0 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66  ded_sql() interf
2f9b0 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ace returns NULL
2f9c0 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
2f9d0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76   memory.** is av
2f9e0 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20  ailable to hold 
2f9f0 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69  the result, or i
2fa00 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75  f the result wou
2fa10 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ld exceed the.**
2fa20 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72   the maximum str
2fa30 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72  ing length deter
2fa40 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51  mined by the [SQ
2fa50 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2fa60 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  H]..**.** ^The [
2fa70 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
2fa80 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
2fa90 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d  -time option lim
2faa0 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a  its the size of.
2fab0 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ** bound paramet
2fac0 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20  er expansions.  
2fad0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  ^The [SQLITE_OMI
2fae0 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  T_TRACE] compile
2faf0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
2fb00 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65  causes sqlite3_e
2fb10 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f  xpanded_sql() to
2fb20 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e   always return N
2fb30 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2fb40 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
2fb50 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2fb60 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6e  P) and sqlite3_n
2fb70 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50 29  ormalized_sql(P)
2fb80 0a 2a 2a 20 61 72 65 20 6d 61 6e 61 67 65 64 20  .** are managed 
2fb90 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 61 72  by SQLite and ar
2fba0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2fbb0 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2fbc0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2fbd0 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2fbe0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2fbf0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2fc00 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2fc10 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2fc20 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2fc30 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2fc40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2fc50 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2fc60 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2fc70 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2fc80 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2fc90 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f  3_free()]..*/.co
2fca0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2fcb0 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
2fcc0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72  mt *pStmt);.char
2fcd0 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   *sqlite3_expand
2fce0 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2fcf0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 6f 6e  tmt *pStmt);.con
2fd00 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2fd10 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2fd20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2fd30 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2fd40 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2fd50 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2fd60 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2fd70 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
2fd80 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2fd90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fda0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2fdb0 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
2fdc0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2fdd0 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
2fde0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
2fdf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fe00 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
2fe10 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
2fe20 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
2fe30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2fe40 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
2fe50 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
2fe60 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2fe70 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
2fe80 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
2fe90 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
2fea0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
2feb0 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
2fec0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
2fed0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
2fee0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2fef0 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
2ff00 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
2ff10 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
2ff20 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
2ff30 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
2ff40 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
2ff50 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
2ff60 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
2ff70 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
2ff80 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2ff90 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
2ffa0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
2ffb0 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
2ffc0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
2ffd0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2ffe0 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
2fff0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
30000 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
30010 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
30020 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
30030 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
30040 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
30050 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
30060 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
30070 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
30080 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
30090 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
300a0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
300b0 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
300c0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
300d0 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
300e0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
300f0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
30100 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
30110 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
30120 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
30130 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
30140 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
30150 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
30160 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
30170 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
30180 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
30190 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
301a0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
301b0 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
301c0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
301d0 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
301e0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
301f0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
30200 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
30210 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
30220 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
30230 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
30240 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
30250 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
30260 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
30270 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
30280 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
30290 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e  es on disk..** ^
302a0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
302b0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65  _readonly() inte
302c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
302d0 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73  ue for [BEGIN] s
302e0 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20  ince.** [BEGIN] 
302f0 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65  merely sets inte
30300 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20  rnal flags, but 
30310 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  the [BEGIN|BEGIN
30320 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a   IMMEDIATE] and.
30330 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  ** [BEGIN|BEGIN 
30340 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61  EXCLUSIVE] comma
30350 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65  nds do touch the
30360 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f   database and so
30370 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
30380 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75  _readonly() retu
30390 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68  rns false for th
303a0 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f  ose commands..*/
303b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
303c0 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
303d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
303e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
303f0 3a 20 51 75 65 72 79 20 54 68 65 20 45 58 50 4c  : Query The EXPL
30400 41 49 4e 20 53 65 74 74 69 6e 67 20 46 6f 72 20  AIN Setting For 
30410 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
30420 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
30430 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
30440 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30450 73 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e 28 53  stmt_isexplain(S
30460 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
30470 72 6e 73 20 31 20 69 66 20 74 68 65 0a 2a 2a 20  rns 1 if the.** 
30480 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30490 6e 74 20 53 20 69 73 20 61 6e 20 45 58 50 4c 41  nt S is an EXPLA
304a0 49 4e 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72  IN statement, or
304b0 20 32 20 69 66 20 74 68 65 0a 2a 2a 20 73 74 61   2 if the.** sta
304c0 74 65 6d 65 6e 74 20 53 20 69 73 20 61 6e 20 45  tement S is an E
304d0 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41  XPLAIN QUERY PLA
304e0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  N..** ^The sqlit
304f0 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69  e3_stmt_isexplai
30500 6e 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  n(S) interface r
30510 65 74 75 72 6e 73 20 30 20 69 66 20 53 20 69 73  eturns 0 if S is
30520 0a 2a 2a 20 61 6e 20 6f 72 64 69 6e 61 72 79 20  .** an ordinary 
30530 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 20 4e  statement or a N
30540 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
30550 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
30560 5f 69 73 65 78 70 6c 61 69 6e 28 73 71 6c 69 74  _isexplain(sqlit
30570 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
30580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30590 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
305a0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
305b0 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
305c0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
305d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
305e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
305f0 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
30600 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
30610 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
30620 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
30630 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
30640 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
30650 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
30660 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
30670 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
30680 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
30690 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
306a0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
306b0 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
306c0 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
306d0 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
306e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
306f0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
30700 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
30710 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
30720 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
30730 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
30740 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
30750 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
30760 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
30770 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
30780 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
30790 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
307a0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
307b0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
307c0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
307d0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
307e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
307f0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
30800 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
30810 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
30820 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
30830 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
30840 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
30850 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
30860 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
30870 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
30880 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
30890 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
308a0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
308b0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
308c0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
308d0 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
308e0 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
308f0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
30900 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
30910 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
30920 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
30930 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
30940 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30950 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
30960 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
30970 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
30980 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
30990 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
309a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
309b0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
309c0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
309d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
309e0 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
309f0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
30a00 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
30a10 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
30a20 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
30a30 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
30a40 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
30a50 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
30a60 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
30a70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
30a80 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
30a90 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
30aa0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
30ab0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
30ac0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
30ad0 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
30ae0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
30af0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
30b00 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
30b10 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
30b20 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
30b30 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
30b40 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
30b50 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
30b60 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
30b70 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
30b80 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
30b90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
30ba0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
30bb0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
30bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
30bd0 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
30be0 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
30bf0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
30c00 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
30c10 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
30c20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
30c30 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
30c40 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
30c50 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
30c60 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
30c70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
30c80 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
30c90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
30ca0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
30cb0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
30cc0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
30cd0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
30ce0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
30cf0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
30d00 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
30d10 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
30d20 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
30d30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
30d40 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
30d50 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
30d60 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
30d70 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
30d80 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
30d90 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
30da0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
30db0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
30dc0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
30dd0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
30de0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
30df0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
30e00 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
30e10 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
30e20 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
30e30 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
30e40 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
30e50 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
30e60 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
30e70 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
30e80 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
30e90 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
30ea0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
30eb0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
30ec0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
30ed0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
30ee0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
30ef0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
30f00 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
30f10 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
30f20 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
30f30 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
30f40 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
30f50 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
30f60 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
30f70 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
30f80 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
30f90 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
30fa0 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
30fb0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
30fc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
30fd0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
30fe0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
30ff0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
31000 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31010 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
31020 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31030 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
31040 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
31050 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
31060 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
31070 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
31080 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
31090 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
310a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
310b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
310c0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
310d0 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a   as arguments.**
310e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
310f0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73  ult_value()], [s
31100 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
31110 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
31120 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
31130 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
31140 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
31150 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
31160 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
31170 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
31180 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
31190 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
311a0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
311b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
311c0 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
311d0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
311e0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
311f0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
31200 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
31210 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
31220 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
31230 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
31240 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
31250 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
31260 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
31270 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
31280 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
31290 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
312a0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
312b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
312c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
312d0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
312e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
312f0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
31300 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
31310 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
31320 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
31330 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
31340 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
31350 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
31360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
31370 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
31380 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
31390 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
313a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
313b0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
313c0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
313d0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
313e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
313f0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
31400 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
31410 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
31420 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
31430 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
31440 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
31450 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
31460 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
31470 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
31480 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
31490 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
314a0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
314b0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
314c0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
314d0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
314e0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
314f0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
31500 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
31510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
31520 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
31530 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
31540 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
31550 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
31560 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
31570 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
31580 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
31590 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
315a0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
315b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
315c0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
315d0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
315e0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
315f0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
31600 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
31610 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
31620 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
31630 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
31640 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
31650 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
31660 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
31670 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
31680 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
31690 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
316a0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
316b0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
316c0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
316d0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
316e0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
316f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
31700 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
31710 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
31720 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
31730 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
31740 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
31750 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
31760 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
31770 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
31780 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
31790 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
317a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
317b0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
317c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
317d0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
317e0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
317f0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
31800 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
31810 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
31820 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
31830 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
31840 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
31850 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
31860 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
31870 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
31880 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
31890 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
318a0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
318b0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
318c0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
318d0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
318e0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
318f0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
31900 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
31910 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
31920 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
31930 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
31940 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
31950 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
31960 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
31970 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
31980 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
31990 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
319a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
319b0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
319c0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
319d0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
319e0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
319f0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
31a00 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
31a10 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
31a20 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
31a30 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
31a40 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
31a50 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
31a60 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
31a70 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
31a80 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
31a90 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
31aa0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
31ab0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
31ac0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
31ad0 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
31ae0 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
31af0 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
31b00 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
31b10 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
31b20 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
31b30 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
31b40 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
31b50 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
31b60 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
31b70 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
31b80 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
31b90 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
31ba0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
31bb0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
31bc0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
31bd0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
31be0 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
31bf0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
31c00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
31c10 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
31c20 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
31c30 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
31c40 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
31c50 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
31c60 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
31c70 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
31c80 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
31c90 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
31ca0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
31cb0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
31cc0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
31cd0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
31ce0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
31cf0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
31d00 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
31d10 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
31d20 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
31d30 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
31d40 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
31d50 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
31d60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
31d70 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
31d80 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
31d90 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
31da0 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
31db0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
31dc0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
31dd0 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
31de0 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
31df0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
31e00 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
31e10 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
31e20 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
31e30 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
31e40 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
31e50 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
31e60 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
31e70 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
31e80 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
31e90 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
31ea0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
31eb0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
31ec0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
31ed0 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
31ee0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
31ef0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
31f00 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
31f10 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
31f20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
31f30 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
31f40 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
31f50 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
31f60 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
31f70 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
31f80 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
31f90 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
31fa0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
31fb0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
31fc0 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
31fd0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
31fe0 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2c   bind API fails,
31ff0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 65 20 64  .** except the d
32000 65 73 74 72 75 63 74 6f 72 20 69 73 20 6e 6f 74  estructor is not
32010 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 74   called if the t
32020 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
32030 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  s a NULL.** poin
32040 74 65 72 20 6f 72 20 74 68 65 20 66 6f 75 72 74  ter or the fourt
32050 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
32060 65 67 61 74 69 76 65 2e 0a 2a 2a 20 5e 49 66 20  egative..** ^If 
32070 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
32080 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
32090 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
320a0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
320b0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
320c0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
320d0 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
320e0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
320f0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
32100 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
32110 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
32120 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
32130 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
32140 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
32150 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
32160 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
32170 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
32180 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
32190 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
321a0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
321b0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
321c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
321d0 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
321e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
321f0 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
32200 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
32210 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
32220 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
32230 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
32240 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
32250 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
32260 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
32270 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
32280 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
32290 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
322a0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
322b0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
322c0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
322d0 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
322e0 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
322f0 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
32300 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
32310 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
32320 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
32330 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
32340 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
32350 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
32360 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
32370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32380 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
32390 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
323a0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
323b0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
323c0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
323d0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
323e0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
323f0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
32400 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
32410 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
32420 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
32430 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
32440 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
32450 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
32460 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
32470 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
32480 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
32490 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
324a0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
324b0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
324c0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
324d0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
324e0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
324f0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
32500 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
32510 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
32520 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  B..**.** ^The sq
32530 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74  lite3_bind_point
32540 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f  er(S,I,P,T,D) ro
32550 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68 65  utine causes the
32560 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   I-th parameter 
32570 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  in.** [prepared 
32580 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20  statement] S to 
32590 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75  have an SQL valu
325a0 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74  e of NULL, but t
325b0 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73  o also be.** ass
325c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
325d0 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79   pointer P of ty
325e0 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69 74  pe T.  ^D is eit
325f0 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
32600 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74  er or.** a point
32610 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74  er to a destruct
32620 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20  or function for 
32630 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  P. ^SQLite will 
32640 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65  invoke the.** de
32650 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
32660 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
32670 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20 69  t of P when it i
32680 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
32690 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70 61  .** P.  The T pa
326a0 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
326b0 65 20 61 20 73 74 61 74 69 63 20 73 74 72 69 6e  e a static strin
326c0 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61 20  g, preferably a 
326d0 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61  string.** litera
326e0 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  l. The sqlite3_b
326f0 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f  ind_pointer() ro
32700 75 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f 66  utine is part of
32710 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72   the.** [pointer
32720 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66 61   passing interfa
32730 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53 51  ce] added for SQ
32740 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a  Lite 3.20.0..**.
32750 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
32760 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
32770 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
32780 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
32790 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
327a0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
327b0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
327c0 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
327d0 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
327e0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
327f0 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
32800 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
32810 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
32820 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
32830 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
32840 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
32850 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
32860 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
32870 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
32880 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
32890 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
328a0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
328b0 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
328c0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
328d0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
328e0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
328f0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
32900 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
32910 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
32920 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
32930 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
32940 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
32950 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
32960 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
32970 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
32980 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
32990 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
329a0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
329b0 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
329c0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
329d0 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
329e0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
329f0 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
32a00 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
32a10 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
32a20 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
32a30 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
32a40 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
32a50 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
32a60 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
32a70 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
32a80 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
32a90 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
32aa0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
32ab0 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
32ac0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
32ad0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
32ae0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
32af0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
32b00 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
32b10 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
32b20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
32b30 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
32b40 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
32b50 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
32b60 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
32b70 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
32b80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
32b90 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32ba0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
32bb0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
32bc0 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
32bd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32be0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
32bf0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
32c00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32c10 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
32c20 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
32c30 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
32c40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
32c50 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
32c60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
32c70 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
32c80 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
32c90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
32ca0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
32cb0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
32cc0 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
32cd0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
32ce0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
32cf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
32d00 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
32d10 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  stmt*,int,const 
32d20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a  char*,int,void(*
32d30 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
32d40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
32d50 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
32d60 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
32d70 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
32d80 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
32d90 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
32da0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
32db0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
32dc0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
32dd0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
32de0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
32df0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
32e00 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
32e10 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ng);.int sqlite3
32e20 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
32e30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
32e40 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
32e50 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
32e60 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
32e70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
32e80 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  nt, void*, const
32e90 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76   char*,void(*)(v
32ea0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
32eb0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
32ec0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
32ed0 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e   int, int n);.in
32ee0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
32ef0 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
32f00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
32f10 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a  lite3_uint64);..
32f20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32f30 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
32f40 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48  rameters.** METH
32f50 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
32f60 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
32f70 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
32f80 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
32f90 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
32fa0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
32fb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32fc0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
32fd0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
32fe0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
32ff0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
33000 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
33010 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
33020 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
33030 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
33040 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
33050 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
33060 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
33070 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
33080 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
33090 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
330a0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
330b0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
330c0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
330d0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
330e0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
330f0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
33100 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
33110 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
33120 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
33130 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
33140 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
33150 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
33160 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
33170 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
33180 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
33190 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
331a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
331b0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
331c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
331d0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
331e0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
331f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
33200 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
33210 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
33220 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
33230 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
33240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
33250 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
33260 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f  rameter.** METHO
33270 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
33280 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33290 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
332a0 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
332b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
332c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
332d0 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
332e0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
332f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33300 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
33310 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
33320 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
33330 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
33340 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
33350 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
33360 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
33370 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
33380 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
33390 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
333a0 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
333b0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
333c0 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
333d0 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
333e0 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
333f0 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
33400 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
33410 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
33420 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
33430 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
33440 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
33450 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
33460 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
33470 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
33480 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
33490 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
334a0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
334b0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
334c0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
334d0 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
334e0 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
334f0 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
33500 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
33510 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
33520 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
33530 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
33540 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
33550 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
33560 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
33570 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
33580 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
33590 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
335a0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
335b0 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71  are16()],.** [sq
335c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
335d0 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  v2()], or [sqlit
335e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
335f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
33600 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
33610 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
33620 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
33630 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
33640 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
33650 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
33660 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
33670 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
33680 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
33690 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
336a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
336b0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
336c0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
336d0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
336e0 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
336f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33700 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
33710 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
33720 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
33730 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
33740 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
33750 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
33760 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
33770 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
33780 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
33790 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
337a0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
337b0 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
337c0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
337d0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
337e0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
337f0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
33800 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
33810 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
33820 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
33830 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
33840 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
33850 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
33860 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
33870 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
33880 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
33890 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
338a0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
338b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
338c0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
338d0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
338e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
338f0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
33900 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
33910 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a  ameter_name()]..
33920 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
33930 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
33940 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
33950 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
33960 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
33970 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
33980 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
33990 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
339a0 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
339b0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
339c0 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
339d0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
339e0 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
339f0 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
33a00 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
33a10 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
33a20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
33a30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33a40 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
33a50 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
33a60 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
33a70 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
33a80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33a90 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
33aa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
33ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33ac0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
33ad0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
33ae0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
33af0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
33b00 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
33b10 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
33b20 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
33b30 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
33b40 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
33b50 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68  atement]. ^If th
33b60 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
33b70 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73  ns 0, that means
33b80 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72   the .** [prepar
33b90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65  ed statement] re
33ba0 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66  turns no data (f
33bb0 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
33bc0 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77  PDATE])..** ^How
33bd0 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75  ever, just becau
33be0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
33bf0 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69  returns a positi
33c00 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e  ve number does n
33c10 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  ot.** mean that 
33c20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73  one or more rows
33c30 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65   of data will be
33c40 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53   returned.  ^A S
33c50 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a  ELECT statement.
33c60 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68  ** will always h
33c70 61 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73  ave a positive s
33c80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
33c90 75 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64  unt() but depend
33ca0 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48  ing on the.** WH
33cb0 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
33cc0 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74  raints and the t
33cd0 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74  able content, it
33ce0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f   might return no
33cf0 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   rows..**.** See
33d00 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
33d10 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
33d20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
33d30 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
33d40 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
33d50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33d60 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
33d70 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
33d80 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33d90 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
33da0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
33db0 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
33dc0 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
33dd0 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
33de0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
33df0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
33e00 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
33e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
33e20 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
33e30 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
33e40 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
33e50 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
33e60 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
33e70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
33e80 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
33e90 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
33ea0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
33eb0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
33ec0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
33ed0 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
33ee0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33ef0 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
33f00 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
33f10 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
33f20 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
33f30 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
33f40 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
33f50 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
33f60 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
33f70 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
33f80 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
33f90 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
33fa0 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
33fb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
33fc0 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
33fd0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
33fe0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
33ff0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
34000 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
34010 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
34020 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
34030 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
34040 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
34050 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
34060 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
34070 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
34080 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
34090 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
340a0 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
340b0 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
340c0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
340d0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
340e0 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
340f0 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
34100 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
34110 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
34120 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
34130 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
34140 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
34150 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
34160 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
34170 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
34180 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
34190 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
341a0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
341b0 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
341c0 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
341d0 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
341e0 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
341f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
34200 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
34210 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
34220 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
34230 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
34240 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
34250 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
34260 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
34270 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
34280 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
34290 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
342a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
342b0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
342c0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
342d0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
342e0 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
342f0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
34300 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
34310 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
34320 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
34330 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
34340 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
34350 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
34360 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
34370 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
34380 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
34390 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
343a0 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
343b0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
343c0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
343d0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
343e0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
343f0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
34400 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
34410 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
34420 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
34430 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
34440 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
34450 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
34460 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
34470 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
34480 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
34490 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
344a0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
344b0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
344c0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
344d0 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
344e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
344f0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
34500 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
34510 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
34520 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
34530 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
34540 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
34550 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
34560 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
34570 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34580 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
34590 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
345a0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
345b0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
345c0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
345d0 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
345e0 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
345f0 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
34600 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
34610 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
34620 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
34630 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
34640 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
34650 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
34660 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
34670 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
34680 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34690 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
346a0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
346b0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
346c0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
346d0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
346e0 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
346f0 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
34700 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
34710 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
34720 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
34730 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
34740 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
34750 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
34760 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
34770 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
34780 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
34790 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
347a0 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
347b0 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
347c0 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
347d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
347e0 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
347f0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
34800 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
34810 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
34820 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
34830 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
34840 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
34850 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
34860 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
34870 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
34880 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
34890 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
348a0 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
348b0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
348c0 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
348d0 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
348e0 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
348f0 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
34900 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
34910 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
34920 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
34930 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
34940 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
34950 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
34960 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
34970 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
34980 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
34990 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
349a0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
349b0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
349c0 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
349d0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
349e0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
349f0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
34a00 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
34a10 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
34a20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34a30 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
34a40 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
34a50 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
34a60 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
34a70 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
34a80 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
34a90 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
34aa0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
34ab0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
34ac0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
34ad0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
34ae0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
34af0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34b00 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
34b10 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
34b20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
34b30 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
34b40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
34b50 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
34b60 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
34b70 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
34b80 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
34b90 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
34ba0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
34bb0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
34bc0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
34bd0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
34be0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
34bf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
34c00 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
34c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
34c20 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
34c30 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
34c40 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
34c50 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
34c60 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
34c70 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
34c80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
34c90 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
34ca0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
34cb0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
34cc0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
34cd0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
34ce0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
34cf0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
34d00 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  tmt.**.** ^(The 
34d10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
34d20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
34d30 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
34d40 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
34d50 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
34d60 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
34d70 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
34d80 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
34d90 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
34da0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
34db0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
34dc0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
34dd0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
34de0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
34df0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
34e00 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
34e10 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
34e20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
34e30 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
34e40 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
34e50 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
34e60 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
34e70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
34e80 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
34e90 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
34ea0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
34eb0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
34ec0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
34ed0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
34ee0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
34ef0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
34f00 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
34f10 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
34f20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
34f30 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
34f40 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
34f50 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
34f60 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
34f70 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
34f80 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
34f90 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
34fa0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
34fb0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
34fc0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
34fd0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
34fe0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
34ff0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
35000 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
35010 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
35020 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
35030 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
35040 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
35050 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
35060 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
35070 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
35080 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
35090 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
350a0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
350b0 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
350c0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
350d0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
350e0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
350f0 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
35100 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
35110 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
35120 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
35130 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
35140 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
35150 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
35160 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
35170 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
35180 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
35190 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
351a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
351b0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
351c0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
351d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
351e0 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
351f0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  L Statement.** M
35200 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
35210 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  tmt.**.** After 
35220 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
35230 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
35240 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 61  prepared using a
35250 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ny of.** [sqlite
35260 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
35270 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
35280 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v3()], [sqlite
35290 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
352a0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
352b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
352c0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
352d0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
352e0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
352f0 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
35300 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
35310 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
35320 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
35330 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
35340 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
35350 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
35360 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
35370 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
35380 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
35390 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
353a0 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
353b0 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
353c0 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
353d0 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
353e0 72 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  r "vX" interface
353f0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
35400 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
35410 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
35420 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
35430 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a 2a  epare16_v3()],.*
35440 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
35450 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
35460 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
35470 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
35480 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
35490 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
354a0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
354b0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
354c0 65 77 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  ew "vX" interfac
354d0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
354e0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
354f0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
35500 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
35510 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
35520 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
35530 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
35540 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
35550 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
35560 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
35570 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
35580 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
35590 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
355a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
355b0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
355c0 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
355d0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
355e0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
355f0 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
35600 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
35610 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
35620 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
35630 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
35640 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
35650 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
35660 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
35670 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
35680 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
35690 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
356a0 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
356b0 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
356c0 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
356d0 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
356e0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
356f0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
35700 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
35710 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
35720 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
35730 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
35740 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
35750 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
35760 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
35770 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
35780 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
35790 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
357a0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
357b0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
357c0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
357d0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
357e0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
357f0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
35800 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
35810 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
35820 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
35830 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
35840 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
35850 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
35860 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
35870 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
35880 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
35890 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
358a0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
358b0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
358c0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
358d0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
358e0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
358f0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
35900 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
35910 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
35920 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
35930 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
35940 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
35950 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
35960 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
35970 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
35980 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
35990 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
359a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
359b0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
359c0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
359d0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
359e0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
359f0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
35a00 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
35a10 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
35a20 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
35a30 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
35a40 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
35a50 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
35a60 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
35a70 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
35a80 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
35a90 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
35aa0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
35ab0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
35ac0 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
35ad0 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
35ae0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
35af0 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
35b00 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
35b10 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
35b20 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
35b30 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
35b40 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
35b50 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
35b60 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
35b70 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
35b80 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
35b90 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
35ba0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
35bb0 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
35bc0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
35bd0 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
35be0 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
35bf0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
35c00 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
35c10 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
35c20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
35c30 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
35c40 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
35c50 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
35c60 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
35c70 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
35c80 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
35c90 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
35ca0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
35cb0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
35cc0 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
35cd0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
35ce0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
35cf0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
35d00 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
35d10 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
35d20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
35d30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
35d40 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
35d50 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
35d60 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
35d70 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
35d80 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
35d90 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
35da0 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
35db0 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
35dc0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
35dd0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
35de0 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
35df0 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
35e00 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
35e10 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
35e20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
35e30 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
35e40 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
35e50 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
35e60 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
35e70 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
35e80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
35e90 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
35ea0 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
35eb0 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
35ec0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
35ed0 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
35ee0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
35ef0 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20   after [version 
35f00 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65  3.6.23.1] ([date
35f10 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a  of:3.6.23.1],.**
35f20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
35f30 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
35f40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
35f50 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
35f60 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
35f70 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
35f80 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
35f90 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
35fa0 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
35fb0 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
35fc0 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
35fd0 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
35fe0 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
35ff0 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
36000 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
36010 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
36020 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
36030 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
36040 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
36050 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
36060 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
36070 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
36080 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
36090 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
360a0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
360b0 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
360c0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
360d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
360e0 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
360f0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
36100 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
36110 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
36120 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
36130 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
36140 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
36150 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
36160 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
36170 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
36180 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
36190 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
361a0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
361b0 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
361c0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
361d0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
361e0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
361f0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
36200 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
36210 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
36220 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
36230 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
36240 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
36250 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
36260 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
36270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
36280 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
36290 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f  _prepare_v3()] o
362a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
362b0 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b  re_v2()].** or [
362c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
362d0 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  6_v2()] or [sqli
362e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
362f0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
36300 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
36310 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
36320 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
36330 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
36340 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
36350 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
36360 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
36370 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
36380 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
36390 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
363a0 75 73 65 20 6f 66 20 74 68 65 20 22 76 58 22 20  use of the "vX" 
363b0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 72 65  interfaces is re
363c0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
363d0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
363e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
363f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36400 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
36410 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
36420 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
36430 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
36440 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
36450 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
36460 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
36470 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
36480 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
36490 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
364a0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
364b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
364c0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
364d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
364e0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
364f0 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
36500 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
36510 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
36520 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
36530 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
36540 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
36550 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
36560 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
36570 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
36580 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
36590 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
365a0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
365b0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
365c0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
365d0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
365e0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
365f0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
36600 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
36610 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
36620 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
36630 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
36640 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
36650 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
36660 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
36670 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
36680 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36690 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
366a0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
366b0 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
366c0 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
366d0 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
366e0 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
366f0 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
36700 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
36710 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
36720 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
36730 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
36740 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
36750 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
36760 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
36770 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
36780 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
36790 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
367a0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
367b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
367c0 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
367d0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
367e0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
367f0 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
36800 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
36810 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
36820 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
36830 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
36840 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
36850 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
36860 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
36870 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
36880 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
36890 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
368a0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
368b0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
368c0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
368d0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
368e0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
368f0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
36900 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
36910 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
36920 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
36930 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
36940 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
36950 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
36960 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
36970 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
36980 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
36990 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
369a0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
369b0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
369c0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
369d0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
369e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
369f0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
36a00 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
36a10 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
36a20 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
36a30 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
36a40 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
36a50 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
36a60 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
36a70 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
36a80 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
36a90 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
36aa0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
36ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36ac0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
36ad0 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
36ae0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
36af0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
36b00 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
36b10 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
36b20 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e   <b>Summary:</b>
36b30 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
36b40 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20  <table border=0 
36b50 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65  cellpadding=0 ce
36b60 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20  llspacing=0>.** 
36b70 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
36b80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f  e3_column_blob</
36b90 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
36ba0 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  BLOB result.** <
36bb0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
36bc0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c  3_column_double<
36bd0 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
36be0 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20  >REAL result.** 
36bf0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
36c00 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62  e3_column_int</b
36c10 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33  ><td>&rarr;<td>3
36c20 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65  2-bit INTEGER re
36c30 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
36c40 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
36c50 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26  n_int64</b><td>&
36c60 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20  rarr;<td>64-bit 
36c70 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a  INTEGER result.*
36c80 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
36c90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36ca0 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
36cb0 64 3e 55 54 46 2d 38 20 54 45 58 54 20 72 65 73  d>UTF-8 TEXT res
36cc0 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
36cd0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
36ce0 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26  _text16</b><td>&
36cf0 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20  rarr;<td>UTF-16 
36d00 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  TEXT result.** <
36d10 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
36d20 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f  3_column_value</
36d30 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
36d40 54 68 65 20 72 65 73 75 6c 74 20 61 73 20 61 6e  The result as an
36d50 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
36d60 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74 65 64 20  lue|unprotected 
36d70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36d80 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  bject..** <tr><t
36d90 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73  d>&nbsp;<td>&nbs
36da0 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20  p;<td>&nbsp;.** 
36db0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
36dc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c  e3_column_bytes<
36dd0 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
36de0 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a  >Size of a BLOB.
36df0 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38 20 54 45  ** or a UTF-8 TE
36e00 58 54 20 72 65 73 75 6c 74 20 69 6e 20 62 79 74  XT result in byt
36e10 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  es.** <tr><td><b
36e20 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
36e30 62 79 74 65 73 31 36 26 6e 62 73 70 3b 26 6e 62  bytes16&nbsp;&nb
36e40 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26  sp;</b>.** <td>&
36e50 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70  rarr;&nbsp;&nbsp
36e60 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55 54 46  ;<td>Size of UTF
36e70 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62  -16.** TEXT in b
36e80 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ytes.** <tr><td>
36e90 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
36ea0 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72  n_type</b><td>&r
36eb0 61 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a  arr;<td>Default.
36ec0 2a 2a 20 64 61 74 61 74 79 70 65 20 6f 66 20 74  ** datatype of t
36ed0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74  he result.** </t
36ee0 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  able></blockquot
36ef0 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61  e>.**.** <b>Deta
36f00 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e  ils:</b>.**.** ^
36f10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
36f20 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
36f30 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
36f40 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
36f50 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
36f60 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
36f70 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
36f80 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
36f90 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
36fa0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
36fb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36fc0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
36fd0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
36fe0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
36ff0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
37000 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
37010 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
37020 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
37030 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
37040 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37050 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
37060 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
37070 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
37080 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
37090 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
370a0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
370b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
370c0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
370d0 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
370e0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
370f0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
37100 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
37110 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
37120 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
37130 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
37140 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
37150 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
37160 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
37170 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
37180 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
37190 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
371a0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
371b0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
371c0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
371d0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
371e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
371f0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
37200 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
37210 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
37220 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
37230 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
37240 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
37250 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
37260 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
37270 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
37280 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
37290 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
372a0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
372b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
372c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
372d0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
372e0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
372f0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
37300 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
37310 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
37320 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
37330 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
37340 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
37350 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
37360 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
37370 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
37380 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
37390 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
373a0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
373b0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
373c0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
373d0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
373e0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
373f0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
37400 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72   first six inter
37410 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64  faces (_blob, _d
37420 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e  ouble, _int, _in
37430 74 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20  t64, _text, and 
37440 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65 61 63 68  _text16).** each
37450 20 72 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75   return the valu
37460 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
37470 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65 63 69 66  lumn in a specif
37480 69 63 20 64 61 74 61 20 66 6f 72 6d 61 74 2e 20  ic data format. 
37490 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c   If.** the resul
374a0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20  t column is not 
374b0 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74 68 65  initially in the
374c0 20 72 65 71 75 65 73 74 65 64 20 66 6f 72 6d 61   requested forma
374d0 74 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  t (for example,.
374e0 2a 2a 20 69 66 20 74 68 65 20 71 75 65 72 79 20  ** if the query 
374f0 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
37500 65 72 20 62 75 74 20 74 68 65 20 73 71 6c 69 74  er but the sqlit
37510 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
37520 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
37530 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74   used to extract
37540 20 74 68 65 20 76 61 6c 75 65 29 20 74 68 65 6e   the value) then
37550 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 74 79   an automatic ty
37560 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  pe conversion is
37570 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a   performed..**.*
37580 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
37590 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
375a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
375b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
375c0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
375d0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
375e0 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
375f0 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
37600 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
37610 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
37620 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
37630 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
37640 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
37650 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
37660 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
37670 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54  LITE_NULL]..** T
37680 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
37690 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
376a0 6e 5f 74 79 70 65 28 29 20 63 61 6e 20 62 65 20  n_type() can be 
376b0 75 73 65 64 20 74 6f 20 64 65 63 69 64 65 20 77  used to decide w
376c0 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66  hich.** of the f
376d0 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61  irst six interfa
376e0 63 65 20 73 68 6f 75 6c 64 20 62 65 20 75 73 65  ce should be use
376f0 64 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65  d to extract the
37700 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a   column value..*
37710 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
37720 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
37730 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
37740 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
37750 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61   if no.** automa
37760 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73  tic type convers
37770 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
37780 65 64 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ed for the value
37790 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a   in question.  .
377a0 2a 2a 20 41 66 74 65 72 20 61 20 74 79 70 65 20  ** After a type 
377b0 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65 20  conversion, the 
377c0 72 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e  result of callin
377d0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  g sqlite3_column
377e0 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e  _type().** is un
377f0 64 65 66 69 6e 65 64 2c 20 74 68 6f 75 67 68 20  defined, though 
37800 68 61 72 6d 6c 65 73 73 2e 20 20 46 75 74 75 72  harmless.  Futur
37810 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
37820 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
37830 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
37840 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
37850 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
37860 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
37870 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  version..**.** I
37880 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
37890 61 20 42 4c 4f 42 20 6f 72 20 61 20 54 45 58 54  a BLOB or a TEXT
378a0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68   string, then th
378b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
378c0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73  _bytes().** or s
378d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
378e0 74 65 73 31 36 28 29 20 69 6e 74 65 72 66 61 63  tes16() interfac
378f0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
37900 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
37910 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20  size.** of that 
37920 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
37930 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
37940 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
37950 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
37960 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
37970 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
37980 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
37990 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
379a0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
379b0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
379c0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
379d0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
379e0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
379f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
37a00 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
37a10 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
37a20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
37a30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
37a40 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
37a50 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
37a60 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
37a70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37a80 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
37a90 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
37aa0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
37ab0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
37ac0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
37ad0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
37ae0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
37af0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
37b00 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
37b10 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
37b20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
37b30 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
37b40 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
37b50 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
37b60 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
37b70 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
37b80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37b90 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
37ba0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
37bb0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
37bc0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
37bd0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
37be0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
37bf0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
37c00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
37c10 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
37c20 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
37c30 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
37c40 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
37c50 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
37c60 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
37c70 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
37c80 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
37c90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
37ca0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
37cb0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
37cc0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
37cd0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
37ce0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
37cf0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
37d00 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
37d10 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
37d20 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
37d30 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
37d40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
37d50 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
37d60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
37d70 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
37d80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
37d90 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
37da0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
37db0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
37dc0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
37dd0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
37de0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
37df0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
37e00 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
37e10 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
37e20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
37e30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
37e40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
37e50 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
37e60 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
37e70 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
37e80 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
37e90 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
37ea0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
37eb0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
37ec0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37ed0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
37ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
37ef0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
37f00 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
37f10 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
37f20 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
37f30 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
37f40 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
37f50 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
37f60 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
37f70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
37f80 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69  ..**.** <b>Warni
37f90 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a  ng:</b> ^The obj
37fa0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
37fb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
37fc0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
37fd0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
37fe0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37ff0 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74  ject.  In a mult
38000 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f  ithreaded enviro
38010 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70  nment,.** an unp
38020 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
38030 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
38040 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73  y only be used s
38050 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73  afely with.** [s
38060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
38070 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
38080 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
38090 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
380a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
380b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
380c0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
380d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
380e0 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
380f0 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
38100 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
38110 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
38120 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
38130 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
38140 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
38150 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
38160 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
38170 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  )], the behavior
38180 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
38190 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68  fe..** Hence, th
381a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
381b0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
381c0 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c  ce.** is normall
381d0 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77 69  y only useful wi
381e0 74 68 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65  thin the impleme
381f0 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b  ntation of .** [
38200 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
38210 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
38220 73 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74  s] or [virtual t
38230 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68  ables], not with
38240 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  in.** top-level 
38250 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
38260 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73  ..**.** The thes
38270 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 61  e routines may a
38280 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
38290 74 20 74 68 65 20 64 61 74 61 74 79 70 65 20 6f  t the datatype o
382a0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  f the result..**
382b0 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69   ^For example, i
382c0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
382d0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
382e0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
382f0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
38300 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
38310 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
38320 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
38330 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
38340 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
38350 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
38360 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
38370 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
38380 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
38390 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
383a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
383b0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
383c0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
383d0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
383e0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
383f0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
38400 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
38410 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
38420 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
38430 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
38440 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
38450 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
38460 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
38470 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
38480 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
38490 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
384a0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
384b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
384c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
384d0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
384e0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
384f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
38500 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
38510 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
38520 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
38530 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
38540 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
38550 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
38560 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
38570 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
38580 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
38590 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
385a0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
385b0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
385c0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
385d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
385e0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
385f0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
38600 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
38610 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
38620 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
38630 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
38640 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
38650 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
38660 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
38670 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
38680 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
38690 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
386a0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
386b0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
386c0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
386d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
386e0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
386f0 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
38700 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
38710 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
38720 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
38730 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
38740 42 20 20 20 20 3c 74 64 3e 20 49