/ Hex Artifact Content
Login

Artifact 1fa197fc89b9924531ab0b6b07e2f7ae3e2862509c32c136e547752cd6374e49:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53 48  ITE_ERROR_SNAPSH
5200: 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  OT          (SQL
5210: 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c 3c  ITE_ERROR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5280: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5460: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5470: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5480: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5490: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54b0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
54c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54d0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
54e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54f0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
5500: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5510: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
5520: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5530: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5540: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5550: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5560: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5570: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5580: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5590: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
55a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55b0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
55c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55d0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
55e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55f0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
5600: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5610: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
5620: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5630: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5640: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5650: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5660: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5670: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5680: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5690: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
56a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56b0: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
56c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
56d0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
56e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
56f0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
5700: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5710: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
5720: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5730: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5740: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5750: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5760: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5770: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5780: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5790: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57b0: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
57c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
57d0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
57e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
57f0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5800: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5810: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5830: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5840: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5850: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5870: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5880: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5890: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
58a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58b0: 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 20  VNODE           
58c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
58d0: 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (27<<8)).#defi
58e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
58f0: 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 20  AUTH            
5900: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5910: 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (28<<8)).#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5930: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 20  BEGIN_ATOMIC    
5940: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5950: 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (29<<8)).#defi
5960: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5970: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 20  COMMIT_ATOMIC   
5980: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5990: 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (30<<8)).#defi
59a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
59b0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 20  ROLLBACK_ATOMIC 
59c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
59d0: 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (31<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
59f0: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5a00: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
5a10: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
5a20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a30: 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  D_VTAB          
5a40: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a50: 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65  D |  (2<<8)).#de
5a60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5a70: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a80: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a90: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ab0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5ac0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5ad0: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5af0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5b00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5b10: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5b40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5b50: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5b60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5b70: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b80: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b90: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5ba0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5bb0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5bc0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5bd0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5be0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5bf0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 44  QLITE_CANTOPEN_D
5c00: 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28 53  IRTYWAL       (S
5c10: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5c20: 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74 20   (5<<8)) /* Not 
5c30: 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Used */.#define 
5c40: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5c50: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5c60: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5c70: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5c80: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5c90: 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20 20  SEQUENCE        
5ca0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5cc0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5cd0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ce0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5cf0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5d00: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5d10: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5d20: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5d30: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5d50: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5d60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5d70: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5d90: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5da0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5db0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5dc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5dd0: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e  _READONLY_CANTIN
5de0: 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  IT       (SQLITE
5df0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c  _READONLY | (5<<
5e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5e10: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45  TE_READONLY_DIRE
5e20: 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49  CTORY      (SQLI
5e30: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36  TE_READONLY | (6
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5e60: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5e70: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5e80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5ea0: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5eb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ec0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5ed0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ee0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5ef0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f00: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f20: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5f30: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5f40: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5f70: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5f80: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5f90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5fa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5fb0: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5fc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5fd0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5fe0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ff0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
6000: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6010: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
6020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6030: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
6040: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
6050: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
6060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6070: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
6080: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
6090: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
60a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
60b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
60c0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
60d0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
60e0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
60f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6100: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
6110: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6120: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
6130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6140: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
6150: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
6160: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
6170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6180: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
6190: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
61a0: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
61c0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
61d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
61e0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
61f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
6200: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
6210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
6220: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  H | (1<<8)).#def
6230: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f  ine SQLITE_OK_LO
6240: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20  AD_PERMANENTLY  
6250: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     (SQLITE_OK | 
6260: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
6270: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
6280: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
6290: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
62a0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
62b0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
62c0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
62d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
62e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
62f0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
6300: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
6310: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
6320: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6330: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
6340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6350: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
6360: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6370: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
6380: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6390: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
63c0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
63d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
63e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6410: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
6420: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6440: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
6450: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
6460: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
6470: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6480: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
6490: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64a0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
64b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
64c0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
64d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64e0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
64f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6500: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6510: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6520: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
6530: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6550: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
6560: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6570: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
6580: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6590: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
65b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
65c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
65d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65e0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
65f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6600: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6620: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6630: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
6640: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6660: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
6670: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
6680: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6690: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
66b0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
66c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
66d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66e0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
66f0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6700: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6710: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6720: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6730: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6740: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6750: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6760: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
6770: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
6780: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6790: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
67b0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
67c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
67d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
67e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6800: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6810: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6820: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6830: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6850: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6860: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
6870: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6880: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
68a0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
68b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
68c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
68d0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
68e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
68f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6900: 30 30 30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  000 */.#define S
6910: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
6920: 44 5f 53 43 48 45 4d 41 20 20 20 20 30 78 30 31  D_SCHEMA    0x01
6930: 30 30 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  000000  /* Ok fo
6940: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6950: 32 28 29 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  2() */.../*.** C
6960: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
6970: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
6980: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
6990: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
69a0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
69b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
69c0: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
69d0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
69e0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
69f0: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6a00: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6a10: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6a20: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6a30: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6a40: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
6a50: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
6a60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6a70: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
6a80: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6a90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6aa0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6ab0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6ac0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6ad0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6ae0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6af0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6b00: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6b10: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6b20: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6b30: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6b40: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6b50: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6b60: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6b70: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6b80: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6b90: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6ba0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6bb0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6bc0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6bd0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6be0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6bf0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6c00: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6c10: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6c20: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6c30: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6c40: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6c50: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6c60: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6c70: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6c80: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6c90: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6ca0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6cb0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6cc0: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6cd0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6ce0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6cf0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6d00: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6d10: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6d20: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6d30: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6d40: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6d50: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6d60: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6d70: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6d80: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6d90: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6da0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6db0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6dc0: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6dd0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6de0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6df0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6e00: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6e10: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6e20: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
6e30: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6e40: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6e50: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6e60: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6e70: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6e80: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6e90: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6ea0: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6eb0: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6ec0: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6ed0: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
6ee0: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  leges..**.** The
6ef0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6f00: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  TCH_ATOMIC prope
6f10: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74  rty means that t
6f20: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
6f30: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70   filesystem supp
6f40: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69  orts doing multi
6f50: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74  ple write operat
6f60: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20  ions atomically 
6f70: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72  when those.** wr
6f80: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
6f90: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20  re bracketed by 
6fa0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
6fb0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
6fc0: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
6fd0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
6fe0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a  OMIC_WRITE]..*/.
6ff0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7000: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
7010: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7020: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
7030: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7040: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
7050: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
7060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7070: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
7080: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7090: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
70a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70b0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
70c0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
70d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
70e0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
70f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7100: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7110: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7120: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7130: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
7140: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7150: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
7160: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
7170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7180: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
7190: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
71a0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
71b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
71c0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
71d0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
71e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
71f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7200: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7210: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7220: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7230: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
7240: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
7250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7260: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
7270: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
7280: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
7290: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
72a0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
72b0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
72c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
72d0: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
72e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
72f0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7300: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
7310: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78  MIC           0x
7320: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
7330: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
7340: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
7350: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
7360: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
7370: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
7380: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
7390: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
73a0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
73b0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
73c0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
73d0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
73e0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
73f0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
7400: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
7410: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
7420: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
7430: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
7440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
7450: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
7460: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7470: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
7480: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
7490: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
74a0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
74b0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
74c0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
74d0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
74e0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
74f0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
7500: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
7510: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7520: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
7530: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
7540: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
7550: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7560: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
7570: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
7580: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7590: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
75a0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
75b0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
75c0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
75d0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
75e0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
75f0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
7600: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
7610: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
7620: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7630: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
7640: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
7650: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
7660: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
7670: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
7680: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
7690: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
76a0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
76b0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
76c0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
76d0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
76e0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
76f0: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7700: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7710: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7720: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7730: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7740: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
7750: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7760: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
7770: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7780: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
7790: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
77a0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
77b0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
77c0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
77d0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
77e0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
77f0: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7800: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7810: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7820: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7830: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7840: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
7850: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
7860: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
7870: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
7880: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
7890: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
78a0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
78b0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
78c0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
78d0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
78e0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
78f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7900: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7910: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7920: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7930: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7940: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7950: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7960: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7970: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
7980: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
7990: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
79a0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
79b0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
79c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
79d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
79e0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
79f0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7a00: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7a10: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7a20: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7a30: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7a40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7a50: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7a60: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
7a70: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
7a80: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7a90: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7aa0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
7ab0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
7ac0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7ad0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7ae0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7af0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7b00: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7b10: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7b20: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7b30: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7b40: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7b50: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7b60: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7b70: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7b80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7b90: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7ba0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7bb0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7bc0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7bd0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7be0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7bf0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7c00: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7c10: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7c20: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7c30: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7c40: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7c50: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7c60: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7c70: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7c80: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7c90: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7ca0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7cb0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7cc0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7cd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7ce0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7cf0: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7d00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7d10: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7d20: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7d30: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7d40: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7d50: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7d60: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7d70: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7d80: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7d90: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7da0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7db0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7dc0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7dd0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7de0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7df0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7e00: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7e10: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7e20: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7e30: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7e40: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7e50: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7e60: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7e70: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7e80: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7e90: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7ea0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7eb0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7ec0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7ed0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7ee0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7ef0: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7f00: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7f10: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7f20: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7f30: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7f40: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7f50: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7f60: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7f70: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7f80: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7f90: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7fa0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7fb0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7fc0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7fd0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7fe0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
7ff0: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
8000: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
8010: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
8020: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
8030: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
8040: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
8050: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
8060: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
8070: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
8080: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
8090: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
80a0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
80b0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
80c0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
80d0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
80e0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
80f0: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
8100: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
8110: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
8120: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
8130: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
8140: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8150: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
8160: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8170: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
8180: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8190: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
81b0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
81c0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
81d0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
81e0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
81f0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
8200: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
8210: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
8220: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
8230: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
8240: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
8250: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
8260: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
8270: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
8280: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
8290: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
82a0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
82b0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
82c0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
82d0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
82e0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
82f0: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
8300: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
8310: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
8320: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
8330: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
8340: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
8350: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8360: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
8370: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
8380: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
8390: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
83a0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
83b0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
83c0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
83d0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
83e0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
83f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
8400: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
8410: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
8420: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
8430: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
8440: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
8450: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
8460: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
8470: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
8480: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
8490: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
84a0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
84b0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
84c0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
84d0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
84e0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
84f0: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
8500: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
8510: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
8520: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
8530: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
8540: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
8550: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
8560: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
8570: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
8580: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
8590: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
85a0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
85b0: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
85c0: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
85d0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
85e0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
85f0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
8600: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
8610: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
8620: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8630: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
8640: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
8650: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
8660: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
8670: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8680: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
8690: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
86a0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
86b0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
86c0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
86d0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
86e0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
86f0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
8700: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8710: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8720: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
8730: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
8740: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
8750: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
8760: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
8770: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
8780: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
8790: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
87a0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
87b0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
87c0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
87d0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
87e0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
87f0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
8800: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8810: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8820: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
8830: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8840: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
8850: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
8860: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
8870: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8880: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
8890: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88a0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
88b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88c0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
88d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88e0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
88f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8900: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8910: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8920: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
8930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8940: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
8950: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8960: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
8970: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8980: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
8990: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
89a0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
89b0: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e  EN_OPEN].** <li>
89c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
89d0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
89e0: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  TE].** <li> [SQL
89f0: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
8a00: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BLE].** <li> [SQ
8a10: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
8a20: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c  _ATOMIC].** </ul
8a30: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8a40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8a50: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8a60: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8a70: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8a80: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8aa0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
8ab0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
8ac0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
8ad0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8ae0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8af0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8b00: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8b10: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8b20: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8b30: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8b40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8b50: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8b60: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8b70: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8b80: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8b90: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8ba0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8bb0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8bc0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8bd0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8be0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8bf0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8c00: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8c10: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8c20: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8c30: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8c40: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8c50: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8c60: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8c70: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8c80: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8c90: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8ca0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8cb0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8cc0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8cd0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8ce0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8cf0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8d00: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8d10: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8d20: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8d30: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8d40: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8d50: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8d60: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8d70: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8d80: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8d90: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8da0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8db0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8dc0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8dd0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8de0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8df0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8e00: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8e10: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8e20: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8e30: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8e40: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8e50: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8e60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8e70: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8e80: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8e90: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8ea0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8eb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ec0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8ed0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8ee0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8ef0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8f00: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
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 2a 70 53  qlite3_int64 *pS
8f30: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8f40: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8f50: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8f60: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8f70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8f80: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8f90: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8fa0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8fb0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8fc0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8fd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8fe0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8ff0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
9000: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
9010: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
9020: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
9030: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
9040: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
9050: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9060: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9070: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
9080: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
9090: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
90a0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
90b0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
90c0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
90d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
90e0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
90f0: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
9100: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
9110: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
9120: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
9130: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
9140: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
9150: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
9160: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
9170: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
9180: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
9190: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
91a0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
91b0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
91c0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
91d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
91e0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
91f0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9200: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
9210: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9220: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
9230: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
9240: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
9250: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
9260: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
9270: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
9280: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
9290: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
92a0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
92b0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
92c0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
92d0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
92e0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
92f0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
9300: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
9310: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
9320: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
9330: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
9340: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
9350: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
9360: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9370: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
9380: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
9390: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
93a0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
93b0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
93c0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
93d0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
93e0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
93f0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9400: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
9410: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
9420: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
9430: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
9440: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
9450: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
9460: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
9470: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
9480: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
9490: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
94a0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
94b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
94c0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
94d0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
94e0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
94f0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9500: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9510: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9520: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
9530: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
9540: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9550: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9560: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9570: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9580: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9590: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
95a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
95b0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
95c0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
95d0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
95e0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
95f0: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9600: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9610: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9620: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9630: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9640: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9650: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9660: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9670: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9680: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
9690: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
96a0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
96b0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
96c0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
96d0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
96e0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
96f0: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9700: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9710: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9720: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9730: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49  TE_FCNTL_SIZE_LI
9740: 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  MIT]].** The [SQ
9750: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9760: 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65 20 69 73  LIMIT] opcode is
9770: 20 75 73 65 64 20 62 79 20 69 6e 2d 6d 65 6d 6f   used by in-memo
9780: 72 79 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 69  ry VFS that.** i
9790: 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71 6c 69 74  mplements [sqlit
97a0: 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29  e3_deserialize()
97b0: 5d 20 74 6f 20 73 65 74 20 61 6e 20 75 70 70 65  ] to set an uppe
97c0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73  r bound on the s
97d0: 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  ize.** of the in
97e0: 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
97f0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9800: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9810: 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  a [sqlite3_int64
9820: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74  ]..** If the int
9830: 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  eger pointed to 
9840: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9850: 6e 20 69 74 20 69 73 20 66 69 6c 6c 65 64 20 69  n it is filled i
9860: 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 63 75  n with the.** cu
9870: 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20 20 4f 74  rrent limit.  Ot
9880: 68 65 72 77 69 73 65 20 74 68 65 20 6c 69 6d 69  herwise the limi
9890: 74 20 69 73 20 73 65 74 20 74 6f 20 74 68 65 20  t is set to the 
98a0: 6c 61 72 67 65 72 20 6f 66 20 74 68 65 20 76 61  larger of the va
98b0: 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  lue.** of the in
98c0: 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f  teger pointed to
98d0: 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
98e0: 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 2e 20   database size. 
98f0: 20 54 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   The integer.** 
9900: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 73 65  pointed to is se
9910: 74 20 74 6f 20 74 68 65 20 6e 65 77 20 6c 69 6d  t to the new lim
9920: 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  it..**.** <li>[[
9930: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
9940: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
9950: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
9960: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
9970: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
9980: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
9990: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
99a0: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
99b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
99c0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
99d0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
99e0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
99f0: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
9a00: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
9a10: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
9a20: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
9a30: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
9a40: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
9a50: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
9a60: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
9a70: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
9a80: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
9a90: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
9aa0: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
9ab0: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
9ac0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
9ad0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
9ae0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
9af0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
9b00: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
9b10: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
9b20: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b30: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9b40: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9b50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9b60: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
9b70: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
9b80: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9b90: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9ba0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9bb0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
9bc0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9bd0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9be0: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9bf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
9c00: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a  NAL_POINTER]..**
9c10: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9c20: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9c30: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9c40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
9c50: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f  URNAL_POINTER] o
9c60: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9c70: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9c80: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9c90: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9ca0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9cb0: 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69  h the journal fi
9cc0: 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68  le (either.** th
9cd0: 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  e [rollback jour
9ce0: 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69  nal] or the [wri
9cf0: 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66  te-ahead log]) f
9d00: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
9d10: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9d20: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9d30: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9d40: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  FILE_POINTER]..*
9d50: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9d60: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9d70: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9d80: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9d90: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9da0: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
9db0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9dc0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
9dd0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9de0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
9df0: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
9e00: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9e10: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
9e20: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
9e30: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
9e40: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
9e50: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
9e60: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
9e70: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9e80: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9e90: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
9ea0: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
9eb0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
9ec0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
9ed0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
9ee0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
9ef0: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
9f00: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9f10: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
9f20: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
9f30: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
9f40: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
9f50: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
9f60: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
9f70: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9f80: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9f90: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
9fa0: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
9fb0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
9fc0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
9fd0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
9fe0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
9ff0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
a000: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
a010: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
a020: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
a030: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
a040: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
a050: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
a060: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
a070: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
a080: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
a090: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a0a0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
a0b0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
a0c0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
a0d0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
a0e0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
a0f0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
a100: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
a110: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a120: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
a130: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
a140: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
a150: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
a160: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
a170: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
a180: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
a190: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
a1a0: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
a1b0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
a1c0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
a1d0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
a1e0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
a1f0: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
a200: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
a210: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
a220: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
a230: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
a240: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
a250: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
a260: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a270: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
a280: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
a290: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
a2a0: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
a2b0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
a2c0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
a2d0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
a2e0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
a2f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
a300: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
a310: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a320: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
a330: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
a340: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
a350: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
a360: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
a370: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
a380: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
a390: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
a3a0: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
a3b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
a3c0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
a3d0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
a3e0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
a3f0: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
a400: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
a410: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
a420: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
a430: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
a440: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
a450: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
a460: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
a470: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
a480: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
a490: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
a4a0: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
a4b0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
a4c0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
a4d0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
a4e0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
a4f0: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
a500: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
a510: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
a520: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
a530: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
a540: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
a550: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
a560: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
a570: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
a580: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
a590: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
a5a0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
a5b0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
a5c0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
a5d0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
a5e0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
a5f0: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
a600: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e  integer is the n
a610: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
a620: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
a630: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
a640: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
a650: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
a660: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
a670: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
a680: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
a690: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
a6a0: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
a6b0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
a6c0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
a6d0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
a6e0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
a6f0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
a700: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
a710: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
a720: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
a730: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
a740: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a750: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
a760: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a770: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
a780: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a790: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a7a0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a7b0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
a7c0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
a7d0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
a7e0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
a7f0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
a800: 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20 61  g ([WAL file]) a
a810: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a820: 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65 64 20 66  .** files used f
a830: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
a840: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
a850: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
a860: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
a870: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
a880: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
a890: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
a8a0: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
a8b0: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
a8c0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
a8d0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
a8e0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
a8f0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
a900: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
a910: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
a920: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
a930: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
a940: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
a950: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
a960: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
a970: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
a980: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
a990: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
a9a0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a9b0: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
a9c0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
a9d0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
a9e0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
a9f0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
aa00: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
aa10: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
aa20: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
aa30: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
aa40: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
aa50: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
aa60: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
aa70: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
aa80: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
aa90: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
aaa0: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
aab0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
aac0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
aad0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
aae0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
aaf0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
ab00: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
ab10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab20: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
ab30: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
ab40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
ab50: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
ab60: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
ab70: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
ab80: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
ab90: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
aba0: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
abb0: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
abc0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
abd0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
abe0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
abf0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
ac00: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
ac10: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
ac20: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
ac30: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
ac40: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
ac50: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
ac60: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
ac70: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
ac80: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
ac90: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
aca0: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
acb0: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
acc0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
acd0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
ace0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
acf0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
ad00: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
ad10: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
ad20: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ad30: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
ad40: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
ad50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ad60: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
ad70: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ad80: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
ad90: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
ada0: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
adb0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
adc0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
add0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
ade0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
adf0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
ae00: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
ae10: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
ae20: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
ae30: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
ae40: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
ae50: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
ae60: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
ae70: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
ae80: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
ae90: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aea0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
aeb0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aec0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
aed0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
aee0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
aef0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
af00: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
af10: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
af20: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
af30: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
af40: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
af50: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
af60: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
af70: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
af80: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
af90: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
afa0: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
afb0: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
afc0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
afd0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
afe0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
aff0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
b000: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
b010: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
b020: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
b030: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
b040: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
b050: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
b060: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
b070: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
b080: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
b090: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
b0a0: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
b0b0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
b0c0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
b0d0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
b0e0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
b0f0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
b100: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
b110: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
b120: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
b130: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
b140: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
b150: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b160: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
b170: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
b180: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
b190: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66  OINTER] opcode f
b1a0: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74  inds a pointer t
b1b0: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a  o the top-level.
b1c0: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65  ** [VFSes] curre
b1d0: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28  ntly in use.  ^(
b1e0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69  The argument X i
b1f0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c  n.** sqlite3_fil
b200: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c  e_control(db,SQL
b210: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
b220: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65  INTER,X) must be
b230: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71  .** of type "[sq
b240: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20  lite3_vfs] **". 
b250: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69   This opcodes wi
b260: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20  ll set *X.** to 
b270: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
b280: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29   top-level VFS.)
b290: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65  ^.** ^When there
b2a0: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46   are multiple VF
b2b0: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73  S shims in the s
b2c0: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64  tack, this opcod
b2d0: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75  e finds the.** u
b2e0: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f  pper-most shim o
b2f0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
b300: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b310: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
b320: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
b330: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
b340: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
b350: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
b360: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b370: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
b380: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
b390: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
b3a0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
b3b0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
b3c0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
b3d0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
b3e0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
b3f0: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
b400: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b410: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b420: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
b430: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
b440: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
b450: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
b460: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
b470: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
b480: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
b490: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
b4a0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
b4b0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
b4c0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
b4d0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
b4e0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
b4f0: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
b500: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
b510: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b520: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
b530: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
b540: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
b550: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
b560: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
b570: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
b580: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b590: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
b5a0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
b5b0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
b5c0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
b5d0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
b5e0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
b5f0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
b600: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
b610: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
b620: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
b630: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b640: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b650: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
b660: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
b670: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
b680: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
b690: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b6a0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
b6b0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
b6c0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
b6d0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
b6e0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
b6f0: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
b700: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
b710: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
b720: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
b730: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
b740: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
b750: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
b760: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
b770: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
b780: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
b790: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
b7a0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
b7b0: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
b7c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b7d0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
b7e0: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
b7f0: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
b800: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
b810: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
b820: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
b830: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
b840: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
b850: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
b860: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
b870: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
b880: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
b890: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
b8a0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
b8b0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
b8c0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b8d0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
b8e0: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
b8f0: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
b900: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
b910: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
b920: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
b930: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
b940: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
b950: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b960: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b970: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
b980: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b990: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
b9a0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
b9b0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
b9c0: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
b9d0: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
b9e0: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
b9f0: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ba00: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ba10: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ba20: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ba30: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ba40: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
ba50: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ba60: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
ba70: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ba80: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
ba90: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
baa0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
bab0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
bac0: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
bad0: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
bae0: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
baf0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
bb00: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
bb10: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
bb20: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
bb30: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
bb40: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
bb50: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
bb60: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
bb70: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
bb80: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
bb90: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
bba0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
bbb0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
bbc0: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
bbd0: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
bbe0: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
bbf0: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
bc00: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
bc10: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bc20: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
bc30: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
bc40: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
bc50: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
bc60: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
bc70: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
bc80: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
bc90: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
bca0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
bcb0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
bcc0: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
bcd0: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
bce0: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
bcf0: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
bd00: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
bd10: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
bd20: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
bd30: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
bd40: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
bd50: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
bd60: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
bd70: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
bd80: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
bd90: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
bda0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
bdb0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
bdc0: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
bdd0: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
bde0: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
bdf0: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
be00: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
be10: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
be20: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
be30: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
be40: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
be50: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
be60: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
be70: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
be80: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
be90: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
bea0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
beb0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
bec0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
bed0: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
bee0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
bef0: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
bf00: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
bf10: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
bf20: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
bf30: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
bf40: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
bf50: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
bf60: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
bf70: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
bf80: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
bf90: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
bfa0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
bfb0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
bfc0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
bfd0: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
bfe0: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
bff0: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
c000: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
c010: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
c020: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
c030: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
c040: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
c050: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
c060: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c070: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
c080: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c090: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
c0a0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
c0b0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
c0c0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
c0d0: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
c0e0: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
c0f0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
c100: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
c110: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
c120: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
c130: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
c140: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
c150: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
c160: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
c170: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
c180: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
c190: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
c1a0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
c1b0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
c1c0: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
c1d0: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
c1e0: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
c1f0: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
c200: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
c210: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
c220: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
c230: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
c240: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
c250: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
c260: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
c270: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
c280: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
c290: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
c2a0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
c2b0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
c2c0: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
c2d0: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
c2e0: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
c2f0: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
c300: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
c310: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
c320: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
c330: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c340: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c350: 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  GET_HANDLE]].** 
c360: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c370: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
c380: 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  LE] opcode can b
c390: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
c3a0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
c3b0: 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68  ng native file h
c3c0: 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64  andle associated
c3d0: 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e   with a file han
c3e0: 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a  dle.  This file.
c3f0: 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  ** control inter
c400: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
c410: 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20  nt as a pointer 
c420: 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65  to a native file
c430: 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77   handle and.** w
c440: 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74  rites the result
c450: 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e  ing value there.
c460: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c470: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c480: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
c490: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c4a0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
c4b0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
c4c0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
c4d0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
c4e0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
c4f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
c500: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
c510: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
c520: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
c530: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
c540: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
c550: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
c560: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
c570: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
c580: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
c590: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
c5a0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
c5b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c5c0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c5d0: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
c5e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c5f0: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
c600: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
c610: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
c620: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
c630: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
c640: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
c650: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
c660: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
c670: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
c680: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
c690: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
c6a0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
c6b0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
c6c0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
c6d0: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
c6e0: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
c6f0: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
c700: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
c710: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
c720: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
c730: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c740: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
c750: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c760: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
c770: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
c780: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
c790: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
c7a0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
c7b0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c7c0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
c7d0: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
c7e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
c7f0: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
c800: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
c810: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
c820: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
c830: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
c840: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
c850: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
c860: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
c870: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c880: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
c890: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a  is opcode.  .**.
c8a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c8b0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
c8c0: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66  IC_WRITE]].** If
c8d0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
c8e0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
c8f0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65  WRITE] opcode re
c900: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c  turns SQLITE_OK,
c910: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c   then.** the fil
c920: 65 20 64 65 73 63 72 69 70 74 6f 72 20 69 73 20  e descriptor is 
c930: 70 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63 68  placed in "batch
c940: 20 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68   write mode", wh
c950: 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c  ich.** means all
c960: 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74   subsequent writ
c970: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c  e operations wil
c980: 6c 20 62 65 20 64 65 66 65 72 72 65 64 20 61 6e  l be deferred an
c990: 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63  d done.** atomic
c9a0: 61 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74  ally at the next
c9b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
c9c0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
c9d0: 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a  TE].  Systems.**
c9e0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70   that do not sup
c9f0: 70 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69  port batch atomi
ca00: 63 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65  c writes will re
ca10: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
ca20: 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77  OUND..** ^Follow
ca30: 69 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c  ing a successful
ca40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45   SQLITE_FCNTL_BE
ca50: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
ca60: 20 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a   and prior to.**
ca70: 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51   the closing [SQ
ca80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
ca90: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  T_ATOMIC_WRITE] 
caa0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  or.** [SQLITE_FC
cab0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
cac0: 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69  MIC_WRITE], SQLi
cad0: 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20  te will make.** 
cae0: 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  no VFS interface
caf0: 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61   calls on the sa
cb00: 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  me [sqlite3_file
cb10: 5d 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  ] file descripto
cb20: 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20  r.** except for 
cb30: 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72  calls to the xWr
cb40: 69 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74  ite method and t
cb50: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
cb60: 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b  method.** with [
cb70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
cb80: 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  E_HINT]..**.** <
cb90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
cba0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
cbb0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  WRITE]].** The [
cbc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
cbd0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
cbe0: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  ] opcode causes 
cbf0: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65  all write.** ope
cc00: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68  rations since th
cc10: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65  e previous succe
cc20: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a  ssful call to .*
cc30: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
cc40: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cc50: 54 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72  TE] to be perfor
cc60: 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a  med atomically..
cc70: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
cc80: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
cc90: 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20  LITE_OK] if and 
cca0: 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69 74  only if the writ
ccb0: 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70  es were.** all p
ccc0: 65 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73  erformed success
ccd0: 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62  fully and have b
cce0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f  een committed to
ccf0: 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72   persistent stor
cd00: 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  age..** ^Regardl
cd10: 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
cd20: 72 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63  r not it is succ
cd30: 65 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c  essful, this fil
cd40: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a  e control takes.
cd50: 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  ** the file desc
cd60: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61  riptor out of ba
cd70: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73  tch write mode s
cd80: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cd90: 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f  quent.** write o
cda0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e  perations are in
cdb0: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53  dependent..** ^S
cdc0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
cdd0: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46   invoke SQLITE_F
cde0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
cdf0: 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74  IC_WRITE without
ce00: 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63  .** a prior succ
ce10: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
ce20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
ce30: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
ce40: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ce50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
ce60: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
ce70: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
ce80: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
ce90: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f  _ATOMIC_WRITE] o
cea0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c  pcode causes all
ceb0: 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74   write.** operat
cec0: 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70  ions since the p
ced0: 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66  revious successf
cee0: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b  ul call to .** [
cef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
cf00: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
cf10: 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61   to be rolled ba
cf20: 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c  ck..** ^This fil
cf30: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20  e control takes 
cf40: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
cf50: 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68  tor out of batch
cf60: 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73   write mode.** s
cf70: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cf80: 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72  quent write oper
cf90: 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70  ations are indep
cfa0: 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69  endent..** ^SQLi
cfb0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
cfc0: 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  voke SQLITE_FCNT
cfd0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
cfe0: 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a  C_WRITE without.
cff0: 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  ** a prior succe
d000: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53  ssful call to [S
d010: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
d020: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  N_ATOMIC_WRITE].
d030: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d040: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54  ITE_FCNTL_LOCK_T
d050: 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65 20  IMEOUT]].** The 
d060: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
d070: 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63 6f  CK_TIMEOUT] opco
d080: 64 65 20 63 61 75 73 65 73 20 61 74 74 65 6d 70  de causes attemp
d090: 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ts to obtain.** 
d0a0: 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69 6e  a file lock usin
d0b0: 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20 78  g the xLock or x
d0c0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20  ShmLock methods 
d0d0: 6f 66 20 74 68 65 20 56 46 53 20 74 6f 20 77 61  of the VFS to wa
d0e0: 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f 20  it.** for up to 
d0f0: 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  M milliseconds b
d100: 65 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20 77  efore failing, w
d110: 68 65 72 65 20 4d 20 69 73 20 74 68 65 20 73 69  here M is the si
d120: 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e 65  ngle .** unsigne
d130: 64 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65  d integer parame
d140: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
d150: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41  [SQLITE_FCNTL_DA
d160: 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20  TA_VERSION]].** 
d170: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d180: 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20  L_DATA_VERSION] 
d190: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
d1a0: 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73  o detect changes
d1b0: 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61 73   to.** a databas
d1c0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 61 72 67  e file.  The arg
d1d0: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
d1e0: 65 72 20 74 6f 20 61 20 33 32 2d 62 69 74 20 75  er to a 32-bit u
d1f0: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e  nsigned integer.
d200: 0a 2a 2a 20 54 68 65 20 22 64 61 74 61 20 76 65  .** The "data ve
d210: 72 73 69 6f 6e 22 20 66 6f 72 20 74 68 65 20 70  rsion" for the p
d220: 61 67 65 72 20 69 73 20 77 72 69 74 74 65 6e 20  ager is written 
d230: 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e 74 65 72  into the pointer
d240: 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61 74 61 20  .  The.** "data 
d250: 76 65 72 73 69 6f 6e 22 20 63 68 61 6e 67 65 73  version" changes
d260: 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 63 68   whenever any ch
d270: 61 6e 67 65 20 6f 63 63 75 72 73 20 74 6f 20 74  ange occurs to t
d280: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
d290: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
d2a0: 65 2c 20 65 69 74 68 65 72 20 74 68 72 6f 75 67  e, either throug
d2b0: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  h SQL statements
d2c0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
d2d0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
d2e0: 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67 68 20 74  ion or through t
d2f0: 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d  ransactions comm
d300: 69 74 74 65 64 20 62 79 20 73 65 70 61 72 61 74  itted by separat
d310: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
d320: 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73 73 69 62  nnections possib
d330: 6c 79 20 69 6e 20 6f 74 68 65 72 20 70 72 6f 63  ly in other proc
d340: 65 73 73 65 73 2e 20 54 68 65 20 5b 73 71 6c 69  esses. The [sqli
d350: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
d360: 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  s()].** interfac
d370: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
d380: 20 66 69 6e 64 20 69 66 20 61 6e 79 20 64 61 74   find if any dat
d390: 61 62 61 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e  abase on the con
d3a0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 63 68 61 6e  nection has chan
d3b0: 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74  ged,.** but that
d3c0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f   interface respo
d3d0: 6e 64 73 20 74 6f 20 63 68 61 6e 67 65 73 20 6f  nds to changes o
d3e0: 6e 20 54 45 4d 50 20 61 73 20 77 65 6c 6c 20 61  n TEMP as well a
d3f0: 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a  s MAIN and does.
d400: 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  ** not provide a
d410: 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65   mechanism to de
d420: 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 20  tect changes to 
d430: 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f  MAIN only.  Also
d440: 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
d450: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d460: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
d470: 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e 61  ponds to interna
d480: 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61  l changes only a
d490: 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e  nd.** omits chan
d4a0: 67 65 73 20 6d 61 64 65 20 62 79 20 6f 74 68 65  ges made by othe
d4b0: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
d4c0: 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
d4d0: 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72  [PRAGMA data_ver
d4e0: 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72  sion] command pr
d4f0: 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73  ovide a mechanis
d500: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d510: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67  ges to.** a sing
d520: 6c 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  le attached data
d530: 62 61 73 65 20 74 68 61 74 20 6f 63 63 75 72 20  base that occur 
d540: 64 75 65 20 74 6f 20 6f 74 68 65 72 20 64 61 74  due to other dat
d550: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d560: 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20  s,.** but omits 
d570: 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e  changes implemen
d580: 74 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  ted by the datab
d590: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
d5a0: 6e 20 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a  n which it is.**
d5b0: 20 63 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66   called.  This f
d5c0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74  ile control is t
d5d0: 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73  he only mechanis
d5e0: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d5f0: 67 65 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70  ges that.** happ
d600: 65 6e 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e  en either intern
d610: 61 6c 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c  ally or external
d620: 6c 79 20 61 6e 64 20 74 68 61 74 20 61 72 65 20  ly and that are 
d630: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
d640: 2a 2a 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ** a particular 
d650: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
d660: 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  e..** </ul>.*/.#
d670: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d680: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
d690: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
d6a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d6b0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
d6c0: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
d6d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d6e0: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
d6f0: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
d700: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d710: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
d720: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
d730: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d740: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
d750: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
d760: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d770: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
d780: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
d790: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
d7a0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
d7b0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
d7c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
d7d0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
d7e0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
d7f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d800: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
d810: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
d820: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
d830: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
d840: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
d850: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
d860: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
d870: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
d880: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
d890: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d8a0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
d8b0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
d8c0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
d8d0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
d8e0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
d8f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
d900: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d910: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
d920: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
d930: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d940: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
d950: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
d960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d970: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
d980: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
d990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d9a0: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
d9b0: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
d9c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d9d0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
d9e0: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
d9f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
da00: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
da10: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
da20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
da30: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
da40: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
da50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
da60: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
da70: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
da80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
da90: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
daa0: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20       24.#define 
dab0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
dac0: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20  VFS             
dad0: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53      25.#define S
dae0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20  QLITE_FCNTL_RBU 
daf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
db00: 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51     26.#define SQ
db10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
db20: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
db30: 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c    27.#define SQL
db40: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
db50: 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  L_POINTER       
db60: 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   28.#define SQLI
db70: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
db80: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
db90: 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  29.#define SQLIT
dba0: 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20  E_FCNTL_PDB     
dbb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
dbc0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
dbd0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
dbe0: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 20 33 31  MIC_WRITE     31
dbf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc00: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
dc10: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a  MIC_WRITE    32.
dc20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dc30: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
dc40: 4f 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23  OMIC_WRITE  33.#
dc50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dc60: 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54  NTL_LOCK_TIMEOUT
dc70: 20 20 20 20 20 20 20 20 20 20 20 33 34 0a 23 64             34.#d
dc80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dc90: 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 20  TL_DATA_VERSION 
dca0: 20 20 20 20 20 20 20 20 20 20 33 35 0a 23 64 65            35.#de
dcb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dcc0: 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 20 20 20  L_SIZE_LIMIT    
dcd0: 20 20 20 20 20 20 20 20 20 33 36 0a 0a 2f 2a 20           36../* 
dce0: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73  deprecated names
dcf0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dd00: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
dd10: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
dd20: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
dd30: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
dd40: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
dd50: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
dd60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
dd70: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
dd80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
dd90: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
dda0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
ddb0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a  _LAST_ERRNO.../*
ddc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
ddd0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
dde0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
ddf0: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
de00: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
de10: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
de20: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
de30: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
de40: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
de50: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
de60: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
de70: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
de80: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
de90: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
dea0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
deb0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
dec0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
ded0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
dee0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
def0: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
df00: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
df10: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
df20: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
df30: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
df40: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
df50: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  EF: Loadable Ext
df60: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a  ension Thunk.**.
df70: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
df80: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74  the opaque sqlit
df90: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
dfa0: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73  structure is pas
dfb0: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68  sed as.** the th
dfc0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
dfd0: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66   entry points of
dfe0: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e   [loadable exten
dff0: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a  sions].  This.**
e000: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
e010: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20  be typedefed in 
e020: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72  order to work ar
e030: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61  ound compiler wa
e040: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d  rnings.** on som
e050: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a  e platforms..*/.
e060: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
e070: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
e080: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  nes sqlite3_api_
e090: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a  routines;../*.**
e0a0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
e0b0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
e0c0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
e0d0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
e0e0: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
e0f0: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
e100: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
e110: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
e120: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
e130: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
e140: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
e150: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
e160: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
e170: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
e180: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
e190: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
e1a0: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
e1b0: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
e1c0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
e1d0: 54 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63  The VFS interfac
e1e0: 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65  e is sometimes e
e1f0: 78 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e  xtended by addin
e200: 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e  g new methods on
e210: 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20  to.** the end.  
e220: 45 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61  Each time such a
e230: 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75  n extension occu
e240: 72 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e  rs, the iVersion
e250: 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63   field.** is inc
e260: 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69  remented.  The i
e270: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74  Version value st
e280: 61 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69  arted out as 1 i
e290: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72  n.** SQLite [ver
e2a0: 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b  sion 3.5.0] on [
e2b0: 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74  dateof:3.5.0], t
e2c0: 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f  hen increased to
e2d0: 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74   2.** with SQLit
e2e0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30  e [version 3.7.0
e2f0: 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37  ] on [dateof:3.7
e300: 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e  .0], and then in
e310: 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20  creased.** to 3 
e320: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72  with SQLite [ver
e330: 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b  sion 3.7.6] on [
e340: 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20  dateof:3.7.6].  
e350: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
e360: 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65  s.** may be appe
e370: 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69  nded to the sqli
e380: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61  te3_vfs object a
e390: 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  nd the iVersion 
e3a0: 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63  value.** may inc
e3b0: 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66  rease again in f
e3c0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
e3d0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74  f SQLite..** Not
e3e0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
e3f0: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
e400: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e410: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
e420: 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d   transition from
e430: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
e440: 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76  ion 3.5.9] to [v
e450: 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e  ersion 3.6.0] on
e460: 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a   [dateof:3.6.0].
e470: 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  ** and yet the i
e480: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
e490: 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a  s not modified..
e4a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
e4b0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
e4c0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
e4d0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
e4e0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
e4f0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
e500: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
e510: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
e520: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
e530: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
e540: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
e550: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
e560: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
e570: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
e580: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
e590: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
e5a0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
e5b0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
e5c0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
e5d0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
e5e0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
e5f0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
e600: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
e610: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
e620: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
e630: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
e640: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
e650: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
e660: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
e670: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
e680: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
e690: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
e6a0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
e6b0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
e6c0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
e6d0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
e6e0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
e6f0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
e700: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
e710: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
e720: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
e730: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
e740: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
e750: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
e760: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
e770: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e780: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
e790: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
e7a0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
e7b0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
e7c0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
e7d0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
e7e0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
e7f0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
e800: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
e810: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
e820: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
e830: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
e840: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
e850: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
e860: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
e870: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
e880: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
e890: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
e8a0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
e8b0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
e8c0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
e8d0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
e8e0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
e8f0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
e900: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
e910: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
e920: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
e930: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e940: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
e950: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
e960: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
e970: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
e980: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
e990: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
e9a0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
e9b0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
e9c0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
e9d0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
e9e0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
e9f0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
ea00: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
ea10: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
ea20: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
ea30: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
ea40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ea50: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ea60: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ea70: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
ea80: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
ea90: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
eaa0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
eab0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
eac0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
ead0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
eae0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
eaf0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
eb00: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
eb10: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
eb20: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
eb30: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
eb40: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
eb50: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
eb60: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
eb70: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
eb80: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
eb90: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
eba0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
ebb0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
ebc0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
ebd0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
ebe0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
ebf0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
ec00: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
ec10: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
ec20: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
ec30: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ec40: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
ec50: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
ec60: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
ec70: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
ec80: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
ec90: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
eca0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
ecb0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
ecc0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
ecd0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
ece0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
ecf0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
ed00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ed10: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
ed20: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
ed30: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
ed40: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
ed50: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ed60: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
ed70: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ed80: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
ed90: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
eda0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
edb0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
edc0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
edd0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
ede0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
edf0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
ee00: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ee10: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
ee20: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ee30: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
ee40: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ee50: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
ee60: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
ee70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
ee80: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
ee90: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
eea0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
eeb0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
eec0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
eed0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
eee0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
eef0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
ef00: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
ef10: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
ef20: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
ef30: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
ef40: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
ef50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ef60: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
ef70: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
ef80: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
ef90: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
efa0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
efb0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
efc0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
efd0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
efe0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
eff0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
f000: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
f010: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
f020: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
f030: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
f040: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f050: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
f060: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
f070: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
f080: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
f090: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
f0a0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
f0b0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
f0c0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
f0d0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
f0e0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
f0f0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
f100: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
f110: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
f120: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
f130: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f140: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
f150: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f160: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
f170: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
f180: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
f190: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
f1a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f1b0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
f1c0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
f1d0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
f1e0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
f1f0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
f200: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
f210: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
f220: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
f230: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
f240: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
f250: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
f260: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
f270: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
f280: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f290: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
f2a0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
f2b0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
f2c0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f2d0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
f2e0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
f2f0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
f300: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
f310: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
f320: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
f330: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
f340: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
f350: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
f360: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
f370: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
f380: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
f390: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
f3a0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
f3b0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
f3c0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
f3d0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
f3e0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
f3f0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
f400: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
f410: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
f420: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
f430: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
f440: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
f450: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
f460: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
f470: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
f480: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
f490: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
f4a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
f4b0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
f4c0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
f4d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
f4e0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
f4f0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
f500: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
f510: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
f520: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
f530: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
f540: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
f550: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
f560: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
f570: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
f580: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
f590: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
f5a0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
f5b0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
f5c0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
f5d0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
f5e0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
f5f0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
f600: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
f610: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
f620: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
f630: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
f640: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
f650: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
f660: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
f670: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
f680: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
f690: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
f6a0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
f6b0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
f6c0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
f6d0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
f6e0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
f6f0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
f700: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
f710: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f720: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
f730: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
f740: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
f750: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
f760: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f770: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
f780: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
f790: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
f7a0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
f7b0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
f7c0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
f7d0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
f7e0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
f7f0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
f800: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
f810: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
f820: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
f830: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
f840: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
f850: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
f860: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
f870: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
f880: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
f890: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
f8a0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
f8b0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
f8c0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
f8d0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
f8e0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
f8f0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
f900: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
f910: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
f920: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
f930: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
f940: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
f950: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
f960: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
f970: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
f980: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
f990: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
f9a0: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
f9b0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
f9c0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
f9d0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
f9e0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
f9f0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
fa00: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
fa10: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
fa20: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
fa30: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
fa40: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
fa50: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
fa60: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
fa70: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
fa80: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
fa90: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
faa0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
fab0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
fac0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
fad0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
fae0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
faf0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
fb00: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
fb10: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
fb20: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
fb30: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
fb40: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
fb50: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
fb60: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
fb70: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
fb80: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
fb90: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
fba0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
fbb0: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
fbc0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
fbd0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
fbe0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
fbf0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
fc00: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
fc10: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
fc20: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
fc30: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
fc40: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
fc50: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
fc60: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
fc70: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
fc80: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
fc90: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
fca0: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
fcb0: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
fcc0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
fcd0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
fce0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
fcf0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
fd00: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
fd10: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
fd20: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
fd30: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
fd40: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
fd50: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
fd60: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
fd70: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
fd80: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
fd90: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
fda0: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
fdb0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
fdc0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
fdd0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
fde0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
fdf0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
fe00: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
fe10: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
fe20: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
fe30: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
fe40: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
fe50: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
fe60: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
fe70: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
fe80: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
fe90: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
fea0: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
feb0: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
fec0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
fed0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
fee0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
fef0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
ff00: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
ff10: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
ff20: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
ff30: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
ff40: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
ff50: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
ff60: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
ff70: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
ff80: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
ff90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
ffa0: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
ffb0: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
ffc0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
ffd0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
ffe0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
fff0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
10000 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
10010 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
10020 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
10030 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
10040 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
10050 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
10060 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
10070 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
10080 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
10090 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
100a0 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
100b0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
100c0 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
100d0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
100e0 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
100f0 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
10100 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
10110 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
10120 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
10130 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
10140 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
10150 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
10160 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
10170 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
10180 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
10190 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
101a0 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
101b0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
101c0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
101d0 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
101e0 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
101f0 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
10200 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
10210 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10220 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
10230 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
10240 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
10250 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
10260 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
10270 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
10280 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
10290 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
102a0 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
102b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
102c0 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
102d0 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
102e0 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
102f0 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
10300 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
10310 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10320 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10330 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
10340 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
10350 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10360 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10370 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
10380 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
10390 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
103a0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
103b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
103c0 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
103d0 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
103e0 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
103f0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10400 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
10410 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
10420 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
10430 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
10440 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
10450 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
10460 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
10470 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
10480 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
10490 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
104a0 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
104b0 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
104c0 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
104d0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
104e0 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
104f0 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
10500 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
10510 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
10520 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
10530 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
10540 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
10550 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
10560 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
10570 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
10580 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
10590 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
105a0 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
105b0 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
105c0 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
105d0 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
105e0 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
105f0 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
10600 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
10610 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
10620 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10630 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
10640 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
10650 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
10660 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
10670 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
10680 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
10690 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
106a0 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
106b0 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
106c0 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
106d0 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
106e0 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
106f0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10700 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
10710 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
10720 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
10730 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
10740 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
10750 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10760 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
10770 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
10780 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
10790 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
107a0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
107b0 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
107c0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
107d0 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
107e0 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
107f0 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
10800 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
10810 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
10820 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
10830 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
10840 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
10850 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
10860 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
10870 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
10880 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10890 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
108a0 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
108b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
108c0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
108d0 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
108e0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
108f0 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
10900 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
10910 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
10920 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
10930 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
10940 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
10950 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
10960 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
10970 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
10980 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
10990 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
109a0 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
109b0 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
109c0 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
109d0 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
109e0 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
109f0 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10a00 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
10a10 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
10a20 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
10a30 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
10a40 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
10a50 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
10a60 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
10a70 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
10a80 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
10a90 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
10aa0 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
10ab0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10ac0 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
10ad0 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
10ae0 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
10af0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
10b00 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
10b10 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
10b20 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
10b30 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
10b40 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
10b50 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10b60 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10b70 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
10b80 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
10b90 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
10ba0 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10bb0 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
10bc0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
10bd0 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
10be0 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
10bf0 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
10c00 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
10c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10c20 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
10c30 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
10c40 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
10c50 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
10c60 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
10c70 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
10c80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10c90 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
10ca0 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
10cb0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
10cc0 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
10cd0 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
10ce0 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
10cf0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
10d00 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
10d10 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
10d20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
10d30 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
10d40 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
10d50 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
10d60 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
10d70 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
10d80 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
10d90 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
10da0 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
10db0 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
10dc0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
10dd0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10de0 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
10df0 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
10e00 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10e10 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10e20 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
10e30 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
10e40 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10e50 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10e60 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
10e70 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
10e80 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
10e90 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
10ea0 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
10eb0 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
10ec0 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
10ed0 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
10ee0 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
10ef0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
10f00 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
10f10 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
10f20 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
10f30 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
10f40 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
10f50 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
10f60 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
10f70 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
10f80 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
10f90 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
10fa0 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
10fb0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10fc0 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
10fd0 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
10fe0 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
10ff0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
11000 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
11010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
11020 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
11030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11040 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
11050 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
11060 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
11070 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
11080 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
11090 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
110a0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
110b0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
110c0 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
110d0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
110e0 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
110f0 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
11100 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
11110 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
11120 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
11130 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
11140 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
11150 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
11160 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
11170 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
11180 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
11190 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
111a0 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
111b0 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
111c0 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
111d0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
111e0 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
111f0 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
11200 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
11210 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
11220 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
11230 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
11240 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11250 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
11260 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
11270 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
11280 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
11290 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
112a0 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
112b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
112c0 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
112d0 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
112e0 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
112f0 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
11300 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
11310 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
11320 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
11330 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
11340 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
11350 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
11360 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11370 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
11380 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
11390 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
113a0 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
113b0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
113c0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
113d0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
113e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
113f0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
11400 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
11410 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
11420 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
11430 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
11440 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
11450 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
11460 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
11470 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
11480 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
11490 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
114a0 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
114b0 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
114c0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
114d0 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
114e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
114f0 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
11500 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11510 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
11520 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
11530 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
11540 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
11550 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
11560 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
11570 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
11580 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
11590 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
115a0 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
115b0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
115c0 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
115d0 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
115e0 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
115f0 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
11600 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
11610 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
11620 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
11630 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
11640 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
11650 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
11660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11670 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
11680 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
11690 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
116a0 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
116b0 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
116c0 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
116d0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
116e0 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
116f0 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
11700 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
11710 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
11720 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
11730 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
11740 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
11750 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
11760 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
11770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
11780 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11790 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
117a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
117b0 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
117c0 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
117d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
117e0 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
117f0 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
11800 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
11810 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
11820 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
11830 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
11840 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
11850 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
11860 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
11870 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
11880 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
11890 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
118a0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
118b0 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
118c0 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
118d0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
118e0 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
118f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
11900 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
11910 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
11920 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11930 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
11940 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
11950 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
11960 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
11970 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
11980 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11990 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
119a0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
119b0 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
119c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
119d0 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
119e0 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
119f0 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
11a00 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
11a10 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11a20 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
11a30 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
11a40 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
11a50 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
11a60 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
11a70 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
11a80 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
11a90 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
11aa0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
11ab0 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
11ac0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
11ad0 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
11ae0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
11af0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11b00 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
11b10 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
11b20 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
11b30 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
11b40 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
11b50 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
11b60 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
11b70 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
11b80 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
11b90 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
11ba0 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
11bb0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
11bc0 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
11bd0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11be0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
11bf0 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
11c00 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11c10 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
11c20 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
11c30 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
11c40 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
11c50 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
11c60 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
11c70 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
11c80 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11c90 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
11ca0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
11cb0 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
11cc0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
11cd0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11ce0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
11cf0 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
11d00 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
11d10 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
11d20 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
11d30 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
11d40 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
11d50 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
11d60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
11d70 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
11d80 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
11d90 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
11da0 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
11db0 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
11dc0 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
11dd0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
11de0 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
11df0 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
11e00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
11e10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
11e20 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
11e30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
11e40 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
11e50 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
11e60 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
11e70 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
11e80 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
11e90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11ea0 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
11eb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
11ec0 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
11ed0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11ee0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11ef0 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
11f00 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
11f10 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
11f20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11f30 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
11f40 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
11f50 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
11f60 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
11f70 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
11f80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
11f90 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
11fa0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
11fb0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
11fc0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11fd0 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
11fe0 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
11ff0 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
12000 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
12010 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
12020 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
12030 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
12040 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
12050 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
12060 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
12070 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
12080 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
12090 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
120a0 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
120b0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
120c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
120d0 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
120e0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
120f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
12100 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
12110 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
12120 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
12130 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12140 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
12150 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
12160 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
12170 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
12180 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
12190 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
121a0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
121b0 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
121c0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
121d0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
121e0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
121f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12200 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
12210 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
12220 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12230 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
12240 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
12250 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
12260 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
12270 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
12280 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
12290 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
122a0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
122b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
122c0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
122d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
122e0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
122f0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
12300 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
12310 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
12320 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
12330 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
12340 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
12350 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
12360 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
12370 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
12380 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
12390 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
123a0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
123b0 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
123c0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
123d0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
123e0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
123f0 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
12400 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
12410 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
12420 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
12430 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
12440 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
12450 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
12460 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
12470 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
12480 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
12490 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
124a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
124b0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
124c0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
124d0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
124e0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
124f0 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
12500 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
12510 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
12520 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
12530 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
12540 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
12550 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
12560 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
12570 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
12580 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
12590 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
125a0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
125b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
125c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
125d0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
125e0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
125f0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12600 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
12610 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
12620 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
12630 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
12640 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
12650 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
12660 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
12670 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
12680 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
12690 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
126a0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
126b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
126c0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
126d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
126e0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
126f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12700 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
12710 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
12720 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
12730 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
12740 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
12750 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
12760 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
12770 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
12780 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
12790 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
127a0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
127b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
127c0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
127d0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
127e0 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
127f0 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
12800 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
12810 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12820 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
12830 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
12840 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
12850 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
12860 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
12870 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
12880 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
12890 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
128a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
128b0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
128c0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
128d0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
128e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
128f0 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
12900 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12910 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
12920 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12930 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
12940 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
12950 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
12960 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12970 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
12980 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
12990 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
129a0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
129b0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
129c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
129d0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
129e0 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
129f0 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
12a00 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
12a10 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
12a20 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
12a30 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
12a40 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12a50 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
12a60 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
12a70 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
12a80 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
12a90 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
12aa0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12ab0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
12ac0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
12ad0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
12ae0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
12af0 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
12b00 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12b10 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
12b20 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
12b30 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
12b40 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
12b50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12b60 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
12b70 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
12b80 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
12b90 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
12ba0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
12bb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12bc0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
12bd0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
12be0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
12bf0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12c00 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
12c10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
12c20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
12c30 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
12c40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12c50 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
12c60 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
12c70 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
12c80 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
12c90 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
12ca0 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
12cb0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12cc0 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
12cd0 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
12ce0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
12cf0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12d00 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
12d10 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
12d20 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
12d30 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
12d40 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
12d50 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
12d60 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
12d70 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
12d80 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
12d90 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
12da0 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
12db0 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
12dc0 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
12dd0 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
12de0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
12df0 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
12e00 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
12e10 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
12e20 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
12e30 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
12e40 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
12e50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12e60 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
12e70 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
12e80 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
12e90 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
12ea0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
12eb0 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
12ec0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
12ed0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
12ee0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
12ef0 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
12f00 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
12f10 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
12f20 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
12f30 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
12f40 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
12f50 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
12f60 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
12f70 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
12f80 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
12f90 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
12fa0 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
12fb0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
12fc0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
12fd0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12fe0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
12ff0 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
13000 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
13010 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
13020 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
13030 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
13040 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
13050 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
13060 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
13070 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
13080 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
13090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
130a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
130b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
130c0 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
130d0 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
130e0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
130f0 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
13100 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
13110 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
13120 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
13130 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
13140 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
13150 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
13160 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
13170 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
13180 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
13190 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
131a0 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
131b0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
131c0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
131d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
131e0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
131f0 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
13200 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
13210 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
13220 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
13230 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
13240 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
13250 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
13260 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
13270 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
13280 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
13290 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
132a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
132b0 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
132c0 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
132d0 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
132e0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
132f0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
13300 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13310 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
13320 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
13330 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
13340 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13350 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
13360 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
13370 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
13380 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
13390 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
133a0 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
133b0 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
133c0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
133d0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
133e0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
133f0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
13400 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
13410 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
13420 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
13430 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
13440 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
13450 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
13460 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
13470 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
13480 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
13490 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
134a0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
134b0 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
134c0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
134d0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
134e0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
134f0 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
13500 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
13510 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
13520 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
13530 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
13540 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
13550 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
13560 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
13570 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
13580 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
13590 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
135a0 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
135b0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
135c0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
135d0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
135e0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
135f0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
13600 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13610 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
13620 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
13630 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
13640 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
13650 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
13660 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
13670 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
13680 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13690 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
136a0 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
136b0 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
136c0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
136d0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
136e0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
136f0 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
13700 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
13710 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
13720 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
13730 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
13740 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
13750 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
13760 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
13770 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
13780 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13790 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
137a0 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
137b0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
137c0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
137d0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
137e0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
137f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
13800 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
13810 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
13820 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
13830 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
13840 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
13850 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
13860 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
13870 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
13880 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
13890 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
138a0 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
138b0 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
138c0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
138d0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
138e0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
138f0 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
13900 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
13910 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
13920 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
13930 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
13940 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
13950 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
13960 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
13970 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
13980 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
13990 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
139a0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
139b0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
139c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
139d0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
139e0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
139f0 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
13a00 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
13a10 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
13a20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
13a30 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13a40 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
13a50 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
13a60 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
13a70 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
13a80 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
13a90 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
13aa0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
13ab0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
13ac0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
13ad0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
13ae0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
13af0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
13b00 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
13b10 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
13b20 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
13b30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13b40 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
13b50 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
13b60 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
13b70 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
13b80 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
13b90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13ba0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
13bb0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
13bc0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
13bd0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13be0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
13bf0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
13c00 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
13c10 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
13c20 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
13c30 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
13c40 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
13c50 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
13c60 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
13c70 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13c80 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
13c90 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
13ca0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
13cb0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
13cc0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
13cd0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
13ce0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13cf0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13d00 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
13d10 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
13d20 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
13d30 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
13d40 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
13d50 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
13d60 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
13d70 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
13d80 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
13d90 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13da0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13db0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13dc0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13dd0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13de0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13df0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
13e00 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
13e10 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
13e20 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
13e30 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
13e40 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
13e50 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
13e60 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13e70 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
13e80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
13e90 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13ea0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13eb0 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
13ec0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13ed0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13ee0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13ef0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
13f00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13f10 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
13f20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
13f30 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
13f40 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
13f50 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
13f60 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
13f70 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
13f80 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
13f90 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
13fa0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
13fb0 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
13fc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13fd0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13fe0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
13ff0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
14000 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
14010 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
14020 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
14030 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14040 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
14050 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
14060 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
14070 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
14080 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
14090 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
140a0 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
140b0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
140c0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
140d0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
140e0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
140f0 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
14100 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14110 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
14120 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
14130 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14140 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14150 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14160 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14170 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14180 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
14190 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
141a0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
141b0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
141c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
141d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
141e0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
141f0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14200 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
14210 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
14220 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
14230 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14240 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
14250 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14260 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
14270 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14280 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
14290 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
142a0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
142b0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
142c0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
142d0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
142e0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
142f0 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
14300 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
14310 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
14320 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
14330 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
14340 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
14350 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
14360 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
14370 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
14380 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
14390 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
143a0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
143b0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
143c0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
143d0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
143e0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
143f0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
14400 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
14410 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
14420 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14430 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
14440 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
14450 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
14460 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
14470 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
14480 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14490 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
144a0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
144b0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
144c0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
144d0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
144e0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
144f0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14500 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14510 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14520 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
14530 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14540 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
14550 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
14560 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
14570 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
14580 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
14590 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
145a0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
145b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
145c0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
145d0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
145e0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
145f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14600 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14610 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14620 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
14630 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
14640 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14650 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14660 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
14670 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14680 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
14690 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
146a0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
146b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
146c0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
146d0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
146e0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
146f0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
14700 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
14710 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
14720 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
14730 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
14740 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14750 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
14760 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
14770 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
14780 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
14790 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
147a0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
147b0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
147c0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
147d0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
147e0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
147f0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
14800 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14810 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
14820 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14830 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
14840 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14850 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14860 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
14870 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14880 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
14890 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
148a0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
148b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
148c0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
148d0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
148e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
148f0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
14900 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14910 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14920 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
14930 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
14940 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
14950 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
14960 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
14970 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
14980 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
14990 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
149a0 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
149b0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
149c0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
149d0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
149e0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
149f0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
14a00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14a10 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20  _SMALL_MALLOC]] 
14a20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14a30 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f  G_SMALL_MALLOC</
14a40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
14a50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14a60 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  MALL_MALLOC opti
14a70 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
14a80 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74  argument of.** t
14a90 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
14aa0 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
14ab0 6e 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65  n, which if true
14ac0 20 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74   provides a hint
14ad0 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68   to.** SQLite th
14ae0 61 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f  at it should avo
14af0 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20  id large memory 
14b00 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70  allocations if p
14b10 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69  ossible..** SQLi
14b20 74 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74  te will run fast
14b30 65 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65  er if it is free
14b40 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d   to make large m
14b50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14b60 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61  s,.** but some a
14b70 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
14b80 20 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73   prefer to run s
14b90 6c 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67  lower in exchang
14ba0 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74  e for.** guarant
14bb0 65 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79  ees about memory
14bc0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74   fragmentation t
14bd0 68 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65  hat are possible
14be0 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c   if large.** all
14bf0 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f  ocations are avo
14c00 69 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74  ided.  This hint
14c10 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66   is normally off
14c20 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14c30 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14c40 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
14c50 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
14c60 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
14c70 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14c80 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14c90 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
14ca0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14cb0 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
14cc0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
14cd0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
14ce0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
14cf0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
14d00 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
14d10 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14d20 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
14d30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14d40 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
14d50 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
14d60 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
14d70 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
14d80 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
14d90 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
14da0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14db0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
14dc0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
14dd0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
14de0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
14df0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
14e00 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
14e10 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14e20 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
14e30 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
14e40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14e50 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
14e60 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
14e70 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
14e80 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
14e90 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
14ea0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
14eb0 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
14ec0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14ed0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
14ee0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
14ef0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
14f00 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14f10 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
14f20 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14f30 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
14f40 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
14f50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
14f60 43 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20  CH option is no 
14f70 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20  longer used..** 
14f80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14f90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14fa0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
14fb0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14fc0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
14fd0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14fe0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
14ff0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
15000 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
15010 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
15020 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
15030 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
15040 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
15050 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
15060 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
15070 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
15080 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
15090 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
150a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
150b0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
150c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
150d0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
150e0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
150f0 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
15100 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
15110 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
15120 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15130 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
15140 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
15150 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
15160 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
15170 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
15180 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
15190 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
151a0 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
151b0 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
151c0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
151d0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
151e0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
151f0 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
15200 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
15210 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
15220 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
15230 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
15240 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
15250 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
15260 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
15270 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
15280 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
15290 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
152a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
152b0 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
152c0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
152d0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
152e0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
152f0 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
15300 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
15310 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
15320 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
15330 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
15340 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
15350 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
15360 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
15370 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
15380 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
15390 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
153a0 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
153b0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
153c0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
153d0 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
153e0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
153f0 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
15400 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
15410 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
15420 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
15430 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
15440 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
15450 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
15460 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
15470 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
15480 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
15490 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
154a0 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
154b0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
154c0 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
154d0 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
154e0 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
154f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15500 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
15510 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
15520 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
15530 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
15540 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
15550 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
15560 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
15570 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
15580 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
15590 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
155a0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
155b0 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
155c0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
155d0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
155e0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
155f0 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
15600 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
15610 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
15620 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
15630 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
15640 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
15650 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
15660 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
15670 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15680 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
15690 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
156a0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
156b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
156c0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
156d0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
156e0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
156f0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
15700 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
15710 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
15720 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15730 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
15740 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
15750 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
15760 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
15770 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
15780 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
15790 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
157a0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
157b0 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
157c0 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
157d0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
157e0 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
157f0 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
15800 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
15810 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
15820 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
15830 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
15840 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
15850 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15860 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
15870 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
15880 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
15890 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
158a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
158b0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
158c0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
158d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
158e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
158f0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
15900 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
15910 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
15920 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
15930 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
15940 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
15950 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
15960 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
15970 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
15980 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
15990 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
159a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
159b0 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
159c0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
159d0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
159e0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
159f0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
15a00 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
15a10 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
15a20 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
15a30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
15a40 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
15a50 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
15a60 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
15a70 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
15a80 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
15a90 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
15aa0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
15ab0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
15ac0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
15ad0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
15ae0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
15af0 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
15b00 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
15b10 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
15b20 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
15b30 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
15b40 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
15b50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15b60 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
15b70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15b80 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
15b90 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15ba0 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
15bb0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15bc0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15bd0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15be0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
15bf0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15c00 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15c10 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
15c20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
15c30 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
15c40 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
15c50 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
15c60 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
15c70 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
15c80 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
15c90 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
15ca0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
15cb0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
15cc0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15cd0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15ce0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
15cf0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
15d00 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15d10 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
15d20 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15d30 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
15d40 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
15d50 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
15d60 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
15d70 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
15d80 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
15d90 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
15da0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
15db0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
15dc0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
15dd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
15de0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
15df0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15e00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15e10 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
15e20 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
15e30 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
15e40 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15e50 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
15e60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15e70 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
15e80 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15e90 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
15ea0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15eb0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
15ec0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
15ed0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
15ee0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15ef0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15f00 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
15f10 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
15f20 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
15f30 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
15f40 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
15f50 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
15f60 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
15f70 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
15f80 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
15f90 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
15fa0 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
15fb0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
15fc0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
15fd0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
15fe0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
15ff0 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
16000 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
16010 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
16020 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
16030 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
16040 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
16050 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
16060 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
16070 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16080 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
16090 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
160a0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
160b0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
160c0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
160d0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
160e0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
160f0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
16100 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
16110 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16120 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
16130 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
16140 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16150 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
16160 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
16170 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16180 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
16190 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
161a0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
161b0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
161c0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
161d0 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
161e0 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
161f0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
16200 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
16210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
16220 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
16230 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
16240 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
16250 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
16260 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
16270 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
16280 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
16290 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
162a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
162b0 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
162c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
162d0 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
162e0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
162f0 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
16300 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16310 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
16320 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
16330 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
16340 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
16350 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
16360 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
16370 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
16380 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
16390 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
163a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
163b0 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
163c0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
163d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
163e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
163f0 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
16400 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16410 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
16420 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
16430 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
16440 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
16450 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
16460 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
16470 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
16480 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
16490 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
164a0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
164b0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
164c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
164d0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
164e0 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
164f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16500 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
16510 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16520 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
16530 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16540 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16550 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
16560 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16570 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
16580 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
16590 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
165a0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
165b0 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
165c0 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
165d0 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
165e0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
165f0 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
16600 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
16610 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16620 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
16630 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
16640 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
16650 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16660 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16670 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
16680 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
16690 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
166a0 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
166b0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
166c0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
166d0 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
166e0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
166f0 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
16700 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
16710 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
16720 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
16730 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
16740 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
16750 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
16760 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
16770 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
16780 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
16790 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
167a0 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
167b0 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
167c0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
167d0 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
167e0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
167f0 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
16800 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
16810 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
16820 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
16830 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
16840 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
16850 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
16860 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
16870 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
16880 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
16890 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
168a0 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
168b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
168c0 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
168d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
168e0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
168f0 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
16900 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
16910 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
16920 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
16930 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
16940 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
16950 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
16960 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
16970 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
16980 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
16990 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
169a0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
169b0 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
169c0 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
169d0 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
169e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
169f0 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
16a00 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
16a10 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
16a20 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
16a30 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
16a40 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
16a50 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
16a60 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
16a70 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
16a80 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
16a90 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
16aa0 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
16ab0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
16ac0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
16ad0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
16ae0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
16af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16b00 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
16b10 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
16b20 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
16b30 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
16b40 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16b50 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
16b60 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
16b70 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
16b80 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16b90 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
16ba0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
16bb0 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
16bc0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
16bd0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
16be0 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
16bf0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16c00 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
16c10 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
16c20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
16c30 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
16c40 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
16c50 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
16c60 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
16c70 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
16c80 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
16c90 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
16ca0 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
16cb0 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
16cc0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
16cd0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
16ce0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
16cf0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
16d00 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
16d10 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
16d20 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
16d30 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
16d40 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
16d50 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
16d60 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
16d70 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
16d80 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
16d90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
16da0 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
16db0 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
16dc0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16dd0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
16de0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
16df0 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
16e00 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
16e10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
16e20 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
16e30 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
16e40 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16e50 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
16e60 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
16e70 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
16e80 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
16e90 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16ea0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
16eb0 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
16ec0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16ed0 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
16ee0 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
16ef0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
16f00 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
16f10 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16f20 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
16f30 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
16f40 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
16f50 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
16f60 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
16f70 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
16f80 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
16f90 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
16fa0 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
16fb0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
16fc0 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
16fd0 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
16fe0 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
16ff0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
17000 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
17010 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
17020 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
17030 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
17040 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
17050 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
17060 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
17070 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
17080 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
17090 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
170a0 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
170b0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
170c0 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
170d0 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
170e0 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
170f0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
17100 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
17110 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
17120 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
17130 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
17140 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
17150 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
17160 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
17170 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17180 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
17190 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
171a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
171b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
171c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
171d0 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
171e0 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
171f0 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
17200 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
17210 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
17220 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
17230 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
17240 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
17250 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
17260 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
17270 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17280 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
17290 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
172a0 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
172b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
172c0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
172d0 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
172e0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
172f0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
17300 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
17310 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
17320 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
17330 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
17340 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
17350 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
17360 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
17370 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
17380 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
17390 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
173a0 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
173b0 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
173c0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
173d0 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
173e0 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
173f0 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
17400 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
17410 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
17420 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
17430 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
17440 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
17450 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
17460 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17470 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
17480 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
17490 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
174a0 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
174b0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
174c0 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
174d0 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
174e0 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
174f0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
17500 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
17510 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
17520 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
17530 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
17540 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
17550 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
17560 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
17570 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
17580 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
17590 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
175a0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
175b0 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
175c0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
175d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
175e0 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
175f0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
17600 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
17610 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
17620 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
17630 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
17640 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17650 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
17660 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
17670 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
17680 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
17690 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
176a0 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
176b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
176c0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
176d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
176e0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
176f0 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
17700 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
17710 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
17720 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
17730 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
17740 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
17750 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
17760 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
17770 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
17780 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
17790 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
177a0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
177b0 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
177c0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
177d0 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
177e0 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
177f0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
17800 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
17810 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
17820 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
17830 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
17840 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
17850 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
17860 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
17870 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
17880 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
17890 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
178a0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
178b0 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
178c0 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
178d0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
178e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
178f0 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
17900 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
17910 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
17920 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
17930 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
17940 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
17950 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
17960 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
17970 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
17980 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
17990 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
179a0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
179b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
179c0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
179d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
179e0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
179f0 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
17a00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
17a10 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
17a20 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
17a30 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
17a40 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
17a50 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
17a60 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
17a70 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
17a80 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
17a90 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
17aa0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17ab0 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
17ac0 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
17ad0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
17ae0 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
17af0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
17b00 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
17b10 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
17b20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17b30 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
17b40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17b50 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
17b60 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17b70 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17b80 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
17b90 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
17ba0 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
17bb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17bc0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
17bd0 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
17be0 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
17bf0 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
17c00 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
17c10 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
17c20 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
17c30 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
17c40 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
17c50 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
17c60 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
17c70 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
17c80 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
17c90 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
17ca0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
17cb0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
17cc0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17cd0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17ce0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
17cf0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17d00 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
17d10 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17d20 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
17d30 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
17d40 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
17d50 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
17d60 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
17d70 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
17d80 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
17d90 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
17da0 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
17db0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
17dc0 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
17dd0 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
17de0 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
17df0 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
17e00 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
17e10 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
17e20 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
17e30 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
17e40 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
17e50 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
17e60 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
17e70 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
17e80 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
17e90 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
17ea0 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
17eb0 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
17ec0 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
17ed0 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
17ee0 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
17ef0 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
17f00 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b  s value..**.** [
17f10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17f20 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a  TMTJRNL_SPILL]].
17f30 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17f40 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
17f50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ILL.** <dd>^The 
17f60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17f70 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74  MTJRNL_SPILL opt
17f80 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17f90 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17fa0 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68  ch.** becomes th
17fb0 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  e [statement jou
17fc0 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64  rnal] spill-to-d
17fd0 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20  isk threshold.  
17fe0 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a  .** [Statement j
17ff0 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c  ournals] are hel
18000 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69  d in memory unti
18010 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e  l their size (in
18020 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65   bytes).** excee
18030 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c  ds this threshol
18040 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e  d, at which poin
18050 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74  t they are writt
18060 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f  en to disk..** O
18070 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f  r if the thresho
18080 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d  ld is -1, statem
18090 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65  ent journals are
180a0 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20   always held.** 
180b0 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d  exclusively in m
180c0 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20  emory..** Since 
180d0 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a  many statement j
180e0 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65  ournals never be
180f0 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74  come large, sett
18100 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a  ing the spill.**
18110 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20   threshold to a 
18120 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34  value such as 64
18130 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20  KiB can greatly 
18140 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e  reduce the amoun
18150 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75  t of.** I/O requ
18160 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ired to support 
18170 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61  statement rollba
18180 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ck..** The defau
18190 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  lt value for thi
181a0 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e  s setting is con
181b0 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a  trolled by the.*
181c0 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52  * [SQLITE_STMTJR
181d0 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c  NL_SPILL] compil
181e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
181f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
18200 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53  NFIG_SORTERREF_S
18210 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
18220 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45  ITE_CONFIG_SORTE
18230 52 52 45 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  RREF_SIZE.** <dd
18240 3e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  >The SQLITE_CONF
18250 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a  IG_SORTERREF_SIZ
18260 45 20 6f 70 74 69 6f 6e 20 61 63 63 65 70 74 73  E option accepts
18270 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
18280 74 65 72 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28  ter.** of type (
18290 69 6e 74 29 20 2d 20 74 68 65 20 6e 65 77 20 76  int) - the new v
182a0 61 6c 75 65 20 6f 66 20 74 68 65 20 73 6f 72 74  alue of the sort
182b0 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69 7a  er-reference siz
182c0 65 20 74 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20  e threshold..** 
182d0 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51  Usually, when SQ
182e0 4c 69 74 65 20 75 73 65 73 20 61 6e 20 65 78 74  Lite uses an ext
182f0 65 72 6e 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72  ernal sort to or
18300 64 65 72 20 72 65 63 6f 72 64 73 20 61 63 63 6f  der records acco
18310 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f  rding.** to an O
18320 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c 20  RDER BY clause, 
18330 61 6c 6c 20 66 69 65 6c 64 73 20 72 65 71 75 69  all fields requi
18340 72 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65  red by the calle
18350 72 20 61 72 65 20 70 72 65 73 65 6e 74 20 69 6e  r are present in
18360 20 74 68 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72   the.** sorted r
18370 65 63 6f 72 64 73 2e 20 48 6f 77 65 76 65 72 2c  ecords. However,
18380 20 69 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   if SQLite deter
18390 6d 69 6e 65 73 20 62 61 73 65 64 20 6f 6e 20 74  mines based on t
183a0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
183b0 0a 2a 2a 20 6f 66 20 61 20 74 61 62 6c 65 20 63  .** of a table c
183c0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 74 73 20 76  olumn that its v
183d0 61 6c 75 65 73 20 61 72 65 20 6c 69 6b 65 6c 79  alues are likely
183e0 20 74 6f 20 62 65 20 76 65 72 79 20 6c 61 72 67   to be very larg
183f0 65 20 2d 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68  e - larger.** th
18400 61 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 65  an the configure
18410 64 20 73 6f 72 74 65 72 2d 72 65 66 65 72 65 6e  d sorter-referen
18420 63 65 20 73 69 7a 65 20 74 68 72 65 73 68 6f 6c  ce size threshol
18430 64 20 2d 20 74 68 65 6e 20 61 20 72 65 66 65 72  d - then a refer
18440 65 6e 63 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65  ence.** is store
18450 64 20 69 6e 20 65 61 63 68 20 73 6f 72 74 65 64  d in each sorted
18460 20 72 65 63 6f 72 64 20 61 6e 64 20 74 68 65 20   record and the 
18470 72 65 71 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20  required column 
18480 76 61 6c 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a  values loaded.**
18490 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
184a0 73 65 20 61 73 20 72 65 63 6f 72 64 73 20 61 72  se as records ar
184b0 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 73 6f  e returned in so
184c0 72 74 65 64 20 6f 72 64 65 72 2e 20 54 68 65 20  rted order. The 
184d0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
184e0 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e   for this option
184f0 20 69 73 20 74 6f 20 6e 65 76 65 72 20 75 73 65   is to never use
18500 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69   this optimizati
18510 6f 6e 2e 20 53 70 65 63 69 66 79 69 6e 67 20 61  on. Specifying a
18520 20 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 76 61   .** negative va
18530 6c 75 65 20 66 6f 72 20 74 68 69 73 20 6f 70 74  lue for this opt
18540 69 6f 6e 20 72 65 73 74 6f 72 65 73 20 74 68 65  ion restores the
18550 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
18560 75 72 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  ur..** This opti
18570 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
18580 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
18590 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
185a0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
185b0 4e 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46  NABLE_SORTER_REF
185c0 45 52 45 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65  ERENCES] compile
185d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
185e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
185f0 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a  FIG_MEMDB_MAXSIZ
18600 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
18610 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42 5f 4d  E_CONFIG_MEMDB_M
18620 41 58 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68  AXSIZE.** <dd>Th
18630 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18640 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45 20 6f 70  MEMDB_MAXSIZE op
18650 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73  tion accepts a s
18660 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a  ingle parameter.
18670 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36  ** [sqlite3_int6
18680 34 5d 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  4] parameter whi
18690 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
186a0 74 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 66  t maximum size f
186b0 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 0a  or an in-memory.
186c0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 72 65 61  ** database crea
186d0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
186e0 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29  e3_deserialize()
186f0 5d 2e 20 20 54 68 69 73 20 64 65 66 61 75 6c 74  ].  This default
18700 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 73 69 7a 65   maximum.** size
18710 20 63 61 6e 20 62 65 20 61 64 6a 75 73 74 65 64   can be adjusted
18720 20 75 70 20 6f 72 20 64 6f 77 6e 20 66 6f 72 20   up or down for 
18730 69 6e 64 69 76 69 64 75 61 6c 20 64 61 74 61 62  individual datab
18740 61 73 65 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  ases using the.*
18750 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
18760 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 5b 73 71 6c  SIZE_LIMIT] [sql
18770 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
18780 6c 7c 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 5d 2e  l|file-control].
18790 20 20 49 66 20 74 68 69 73 0a 2a 2a 20 63 6f 6e    If this.** con
187a0 66 69 67 75 72 61 74 69 6f 6e 20 73 65 74 74 69  figuration setti
187b0 6e 67 20 69 73 20 6e 65 76 65 72 20 75 73 65 64  ng is never used
187c0 2c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  , then the defau
187d0 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 64 65  lt maximum is de
187e0 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74  termined.** by t
187f0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 45 4d 44 42  he [SQLITE_MEMDB
18800 5f 44 45 46 41 55 4c 54 5f 4d 41 58 53 49 5a 45  _DEFAULT_MAXSIZE
18810 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
18820 70 74 69 6f 6e 2e 20 20 49 66 20 74 68 61 74 0a  ption.  If that.
18830 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
18840 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 74 20 73 65  option is not se
18850 74 2c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  t, then the defa
18860 75 6c 74 20 6d 61 78 69 6d 75 6d 20 69 73 20 31  ult maximum is 1
18870 30 37 33 37 34 31 38 32 34 2e 0a 2a 2a 20 3c 2f  073741824..** </
18880 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
18890 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
188a0 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
188b0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
188c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
188d0 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
188e0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
188f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18900 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
18910 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
18920 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18930 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
18940 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
18950 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
18960 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18970 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
18980 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
18990 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
189a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
189b0 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
189c0 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65    6  /* No longe
189d0 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
189e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
189f0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
18a00 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
18a10 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
18a20 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18a30 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
18a40 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
18a50 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
18a60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18a70 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
18a80 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
18a90 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
18aa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
18ab0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
18ac0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
18ad0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
18ae0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18af0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
18b00 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
18b10 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
18b20 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
18b30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
18b40 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
18b50 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
18b60 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
18b70 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
18b80 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
18b90 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18ba0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18bb0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
18bc0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
18bd0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18be0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
18bf0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
18c00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18c10 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
18c20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
18c30 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
18c40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
18c50 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
18c60 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
18c70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
18c80 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
18c90 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
18ca0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
18cb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18cc0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
18cd0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
18ce0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
18cf0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18d00 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
18d10 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
18d20 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
18d30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18d40 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
18d50 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
18d60 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
18d70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
18d80 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
18d90 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
18da0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
18db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18dc0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
18dd0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
18de0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
18df0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18e00 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
18e10 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
18e20 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
18e30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18e40 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
18e50 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
18e60 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
18e70 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  a */.#define SQL
18e80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
18e90 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32  RNL_SPILL      2
18ea0 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  6  /* int nByte 
18eb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ec0 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
18ed0 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20  ALLOC        27 
18ee0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
18ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18f00 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53  NFIG_SORTERREF_S
18f10 49 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20  IZE      28  /* 
18f20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
18f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18f40 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a 45  IG_MEMDB_MAXSIZE
18f50 20 20 20 20 20 20 20 32 39 20 20 2f 2a 20 73 71         29  /* sq
18f60 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a  lite3_int64 */..
18f70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18f80 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
18f90 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
18fa0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
18fb0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
18fc0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
18fd0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
18fe0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
18ff0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
19000 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
19010 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
19020 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
19030 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
19040 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
19050 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
19060 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
19070 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
19080 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
19090 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
190a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
190b0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
190c0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
190d0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
190e0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
190f0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
19100 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
19110 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
19120 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
19130 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
19140 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
19150 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
19160 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
19170 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
19180 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
19190 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
191a0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
191b0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
191c0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
191d0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
191e0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
191f0 49 44 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IDE]].** <dt>SQL
19200 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
19210 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
19220 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
19230 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
19240 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
19250 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
19260 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
19270 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
19280 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
19290 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
192a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
192b0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
192c0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
192d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
192e0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
192f0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
19300 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
19310 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
19320 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
19330 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
19340 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
19350 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
19360 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
19370 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
19380 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
19390 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
193a0 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
193b0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
193c0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
193d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
193e0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
193f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
19400 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
19410 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
19420 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
19430 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
19440 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
19450 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
19460 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
19470 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
19480 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
19490 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
194a0 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
194b0 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
194c0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
194d0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
194e0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
194f0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
19500 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
19510 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
19520 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
19530 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
19540 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
19550 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
19560 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
19570 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
19580 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
19590 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
195a0 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
195b0 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
195c0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
195d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
195e0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
195f0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
19600 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
19610 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
19620 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
19630 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
19640 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
19650 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
19660 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
19670 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
19680 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
19690 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
196a0 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
196b0 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
196c0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
196d0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
196e0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
196f0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
19700 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
19710 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
19720 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
19730 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
19740 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
19750 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
19760 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
19770 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
19780 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
19790 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
197a0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
197b0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
197c0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
197d0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
197e0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
197f0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
19800 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
19810 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
19820 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
19830 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
19840 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19850 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19860 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19870 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
19880 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
19890 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
198a0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
198b0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
198c0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
198d0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
198e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
198f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
19900 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
19910 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
19920 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
19930 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
19940 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
19950 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
19960 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19970 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19980 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
19990 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
199a0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
199b0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
199c0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
199d0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
199e0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
199f0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19a00 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 5d 5d  ENABLE_TRIGGER]]
19a10 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19a20 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
19a30 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
19a40 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
19a50 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
19a60 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
19a70 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
19a80 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
19a90 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
19aa0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
19ab0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
19ac0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
19ad0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
19ae0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
19af0 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
19b00 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
19b10 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
19b20 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
19b30 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
19b40 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
19b50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
19b60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
19b70 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
19b80 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
19b90 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
19ba0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
19bb0 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
19bc0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
19bd0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
19be0 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
19bf0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
19c00 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
19c10 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
19c20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
19c30 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
19c40 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
19c50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
19c60 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19c70 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
19c80 45 52 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ER]].** <dt>SQLI
19c90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19ca0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
19cb0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
19cc0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
19cd0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
19ce0 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20   disable the.** 
19cf0 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28  [fts3_tokenizer(
19d00 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63  )] function whic
19d10 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  h is part of the
19d20 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d  .** [FTS3] full-
19d30 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69  text search engi
19d40 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a  ne extension..**
19d50 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
19d60 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19d70 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
19d80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19d90 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
19da0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
19db0 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
19dc0 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69  zer() or.** posi
19dd0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66  tive to enable f
19de0 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
19df0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
19e00 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
19e10 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  .** unchanged..*
19e20 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
19e30 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
19e40 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
19e50 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
19e60 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
19e70 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
19e80 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e  ether fts3_token
19e90 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
19ea0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
19eb0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
19ec0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
19ed0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
19ee0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
19ef0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
19f00 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
19f10 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
19f20 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
19f30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
19f40 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
19f50 44 5f 45 58 54 45 4e 53 49 4f 4e 5d 5d 0a 2a 2a  D_EXTENSION]].**
19f60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19f70 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
19f80 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a  _EXTENSION</dt>.
19f90 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
19fa0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
19fb0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
19fc0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
19fd0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
19fe0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e  .** interface in
19ff0 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74  dependently of t
1a000 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he [load_extensi
1a010 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  on()] SQL functi
1a020 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  on..** The [sqli
1a030 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
1a040 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49  extension()] API
1a050 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
1a060 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a  bles both the.**
1a070 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f   C-API [sqlite3_
1a080 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1a090 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  ] and the SQL fu
1a0a0 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74  nction [load_ext
1a0b0 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68  ension()]..** Th
1a0c0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
1a0d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
1a0e0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20  uments..** When 
1a0f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1a100 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72  nt to this inter
1a110 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20  face is 1, then 
1a120 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69  only the C-API i
1a130 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64  s.** enabled and
1a140 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
1a150 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c  n remains disabl
1a160 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  ed.  If the firs
1a170 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  t argument to.**
1a180 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1a190 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20  is 0, then both 
1a1a0 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68  the C-API and th
1a1b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
1a1c0 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20  re disabled..** 
1a1d0 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
1a1e0 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65  ument is -1, the
1a1f0 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65  n no changes are
1a200 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f   made to state o
1a210 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  f either the.** 
1a220 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c  C-API or the SQL
1a230 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
1a240 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a250 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
1a260 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
1a270 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
1a280 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
1a290 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
1a2a0 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  r [sqlite3_load_
1a2b0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
1a2c0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73  erface.** is dis
1a2d0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
1a2e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
1a2f0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
1a300 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a  d parameter may.
1a310 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ** be a NULL poi
1a320 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63  nter, in which c
1a330 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
1a340 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
1a350 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64  ted back..** </d
1a360 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
1a370 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
1a380 42 4e 41 4d 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  BNAME]] <dt>SQLI
1a390 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
1a3a0 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBNAME</dt>.** <
1a3b0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
1a3c0 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e   is used to chan
1a3d0 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ge the name of t
1a3e0 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61  he "main" databa
1a3f0 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e  se.** schema.  ^
1a400 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e  The sole argumen
1a410 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
1a420 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46  o a constant UTF
1a430 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63  8 string.** whic
1a440 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  h will become th
1a450 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d  e new schema nam
1a460 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  e in place of "m
1a470 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a  ain".  ^SQLite.*
1a480 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20  * does not make 
1a490 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65  a copy of the ne
1a4a0 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61  w main schema na
1a4b0 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68  me string, so th
1a4c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
1a4d0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
1a4e0 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  t the argument p
1a4f0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20  assed into this 
1a500 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20  DBCONFIG option 
1a510 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  is unchanged.** 
1a520 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20  until after the 
1a530 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a540 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c  ion closes..** <
1a550 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
1a560 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
1a570 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 5d 5d 20  CKPT_ON_CLOSE]] 
1a580 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
1a590 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
1a5a0 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
1a5b0 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
1a5c0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
1a5d0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
1a5e0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
1a5f0 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
1a600 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
1a610 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
1a620 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
1a630 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
1a640 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
1a650 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
1a660 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
1a670 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
1a680 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
1a690 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
1a6a0 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
1a6b0 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
1a6c0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
1a6d0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
1a6e0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
1a6f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1a700 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
1a710 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
1a720 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70  s an integer - p
1a730 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61 62  ositive to disab
1a740 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
1a750 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
1a760 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
1a770 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
1a780 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74  , and negative t
1a790 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
1a7a0 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
1a7b0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
1a7c0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
1a7d0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
1a7e0 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
1a7f0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
1a800 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
1a810 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
1a820 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
1a830 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
1a840 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
1a850 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
1a860 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
1a870 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
1a880 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a890 4e 41 42 4c 45 5f 51 50 53 47 5d 5d 20 3c 64 74  NABLE_QPSG]] <dt
1a8a0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1a8b0 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74  _ENABLE_QPSG</dt
1a8c0 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  >.** <dd>^(The S
1a8d0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a8e0 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f  NABLE_QPSG optio
1a8f0 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
1a900 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68  eactivates.** th
1a910 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  e [query planner
1a920 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61   stability guara
1a930 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57  ntee] (QPSG).  W
1a940 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20  hen the QPSG is 
1a950 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e  active,.** a sin
1a960 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74  gle SQL query st
1a970 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77  atement will alw
1a980 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
1a990 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72   algorithm regar
1a9a0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75  dless.** of valu
1a9b0 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  es of [bound par
1a9c0 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20  ameters].)^ The 
1a9d0 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f  QPSG disables so
1a9e0 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  me query optimiz
1a9f0 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c  ations.** that l
1aa00 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65  ook at the value
1aa10 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d  s of bound param
1aa20 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e  eters, which can
1aa30 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69   make some queri
1aa40 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42  es.** slower.  B
1aa50 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20  ut the QPSG has 
1aa60 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66  the advantage of
1aa70 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c   more predictabl
1aa80 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74  e behavior.  Wit
1aa90 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63  h.** the QPSG ac
1aaa0 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c  tive, SQLite wil
1aab0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
1aac0 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e   same query plan
1aad0 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73   in the field as
1aae0 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72  .** was used dur
1aaf0 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74  ing testing in t
1ab00 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66  he lab..** The f
1ab10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1ab20 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
1ab30 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
1ab40 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
1ab50 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20  e .** the QPSG, 
1ab60 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
1ab70 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61  le QPSG, or nega
1ab80 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1ab90 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
1aba0 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f  hanged. The seco
1abb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1abc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1abd0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
1abe0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
1abf0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
1ac00 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65 20  ate whether the 
1ac10 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65 64  QPSG is disabled
1ac20 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
1ac30 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
1ac40 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ll..** </dd>.**.
1ac50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
1ac60 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
1ac70 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ]] <dt>SQLITE_DB
1ac80 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45  CONFIG_TRIGGER_E
1ac90 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  QP</dt>.** <dd> 
1aca0 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
1acb0 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49  output of EXPLAI
1acc0 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d  N QUERY PLAN com
1acd0 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a  mands does not .
1ace0 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75  ** include outpu
1acf0 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74  t for any operat
1ad00 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62  ions performed b
1ad10 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  y trigger progra
1ad20 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69  ms. This.** opti
1ad30 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  on is used to se
1ad40 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20  t or clear (the 
1ad50 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20  default) a flag 
1ad60 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69  that governs thi
1ad70 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54  s.** behavior. T
1ad80 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1ad90 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
1ada0 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  s operation is a
1adb0 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70  n integer -.** p
1adc0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1add0 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69  e output for tri
1ade0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f  gger programs, o
1adf0 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c  r zero to disabl
1ae00 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61  e it,.** or nega
1ae10 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1ae20 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
1ae30 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
1ae40 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1ae50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1ae60 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
1ae70 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a  ch is written .*
1ae80 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  * 0 or 1 to indi
1ae90 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75 74  cate whether out
1aea0 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73  put-for-triggers
1aeb0 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c   has been disabl
1aec0 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74  ed - 0 if .** it
1aed0 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64   is not disabled
1aee0 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a  , 1 if it is.  .
1aef0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
1af00 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
1af10 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 5d  _RESET_DATABASE]
1af20 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  ] <dt>SQLITE_DBC
1af30 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41  ONFIG_RESET_DATA
1af40 42 41 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  BASE</dt>.** <dd
1af50 3e 20 53 65 74 20 74 68 65 20 53 51 4c 49 54 45  > Set the SQLITE
1af60 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f  _DBCONFIG_RESET_
1af70 44 41 54 41 42 41 53 45 20 66 6c 61 67 20 61 6e  DATABASE flag an
1af80 64 20 74 68 65 6e 20 72 75 6e 0a 2a 2a 20 5b 56  d then run.** [V
1af90 41 43 55 55 4d 5d 20 69 6e 20 6f 72 64 65 72 20  ACUUM] in order 
1afa0 74 6f 20 72 65 73 65 74 20 61 20 64 61 74 61 62  to reset a datab
1afb0 61 73 65 20 62 61 63 6b 20 74 6f 20 61 6e 20 65  ase back to an e
1afc0 6d 70 74 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mpty database.**
1afd0 20 77 69 74 68 20 6e 6f 20 73 63 68 65 6d 61 20   with no schema 
1afe0 61 6e 64 20 6e 6f 20 63 6f 6e 74 65 6e 74 2e 20  and no content. 
1aff0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  The following pr
1b000 6f 63 65 73 73 20 77 6f 72 6b 73 20 65 76 65 6e  ocess works even
1b010 20 66 6f 72 0a 2a 2a 20 61 20 62 61 64 6c 79 20   for.** a badly 
1b020 63 6f 72 72 75 70 74 65 64 20 64 61 74 61 62 61  corrupted databa
1b030 73 65 20 66 69 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e  se file:.** <ol>
1b040 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 74 68 65 20  .** <li> If the 
1b050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b060 69 6f 6e 20 69 73 20 6e 65 77 6c 79 20 6f 70 65  ion is newly ope
1b070 6e 65 64 2c 20 6d 61 6b 65 20 73 75 72 65 20 69  ned, make sure i
1b080 74 20 68 61 73 20 72 65 61 64 20 74 68 65 0a 2a  t has read the.*
1b090 2a 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20  *      database 
1b0a0 73 63 68 65 6d 61 20 62 79 20 70 72 65 70 61 72  schema by prepar
1b0b0 69 6e 67 20 74 68 65 6e 20 64 69 73 63 61 72 64  ing then discard
1b0c0 69 6e 67 20 73 6f 6d 65 20 71 75 65 72 79 20 61  ing some query a
1b0d0 67 61 69 6e 73 74 20 74 68 65 0a 2a 2a 20 20 20  gainst the.**   
1b0e0 20 20 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20     database, or 
1b0f0 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
1b100 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
1b110 61 64 61 74 61 28 29 2c 20 69 67 6e 6f 72 69 6e  adata(), ignorin
1b120 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 65 72  g any.**      er
1b130 72 6f 72 73 2e 20 20 54 68 69 73 20 73 74 65 70  rors.  This step
1b140 20 69 73 20 6f 6e 6c 79 20 6e 65 63 65 73 73 61   is only necessa
1b150 72 79 20 69 66 20 74 68 65 20 61 70 70 6c 69 63  ry if the applic
1b160 61 74 69 6f 6e 20 64 65 73 69 72 65 73 20 74 6f  ation desires to
1b170 20 6b 65 65 70 0a 2a 2a 20 20 20 20 20 20 74 68   keep.**      th
1b180 65 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41  e database in WA
1b190 4c 20 6d 6f 64 65 20 61 66 74 65 72 20 74 68 65  L mode after the
1b1a0 20 72 65 73 65 74 20 69 66 20 69 74 20 77 61 73   reset if it was
1b1b0 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20 62 65 66   in WAL mode bef
1b1c0 6f 72 65 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  ore.**      the 
1b1d0 72 65 73 65 74 2e 20 20 0a 2a 2a 20 3c 6c 69 3e  reset.  .** <li>
1b1e0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
1b1f0 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42  ig(db, SQLITE_DB
1b200 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54  CONFIG_RESET_DAT
1b210 41 42 41 53 45 2c 20 31 2c 20 30 29 3b 0a 2a 2a  ABASE, 1, 0);.**
1b220 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 65   <li> [sqlite3_e
1b230 78 65 63 5d 28 64 62 2c 20 22 5b 56 41 43 55 55  xec](db, "[VACUU
1b240 4d 5d 22 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  M]", 0, 0, 0);.*
1b250 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 64  * <li> sqlite3_d
1b260 62 5f 63 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c  b_config(db, SQL
1b270 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53  ITE_DBCONFIG_RES
1b280 45 54 5f 44 41 54 41 42 41 53 45 2c 20 30 2c 20  ET_DATABASE, 0, 
1b290 30 29 3b 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20  0);.** </ol>.** 
1b2a0 42 65 63 61 75 73 65 20 72 65 73 65 74 74 69 6e  Because resettin
1b2b0 67 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20  g a database is 
1b2c0 64 65 73 74 72 75 63 74 69 76 65 20 61 6e 64 20  destructive and 
1b2d0 69 72 72 65 76 65 72 73 69 62 6c 65 2c 20 74 68  irreversible, th
1b2e0 65 0a 2a 2a 20 70 72 6f 63 65 73 73 20 72 65 71  e.** process req
1b2f0 75 69 72 65 73 20 74 68 65 20 75 73 65 20 6f 66  uires the use of
1b300 20 74 68 69 73 20 6f 62 73 63 75 72 65 20 41 50   this obscure AP
1b310 49 20 61 6e 64 20 6d 75 6c 74 69 70 6c 65 20 73  I and multiple s
1b320 74 65 70 73 20 74 6f 20 68 65 6c 70 0a 2a 2a 20  teps to help.** 
1b330 65 6e 73 75 72 65 20 74 68 61 74 20 69 74 20 64  ensure that it d
1b340 6f 65 73 20 6e 6f 74 20 68 61 70 70 65 6e 20 62  oes not happen b
1b350 79 20 61 63 63 69 64 65 6e 74 2e 0a 2a 2a 0a 2a  y accident..**.*
1b360 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1b370 46 49 47 5f 44 45 46 45 4e 53 49 56 45 5d 5d 20  FIG_DEFENSIVE]] 
1b380 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1b390 46 49 47 5f 44 45 46 45 4e 53 49 56 45 3c 2f 64  FIG_DEFENSIVE</d
1b3a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  t>.** <dd>The SQ
1b3b0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45  LITE_DBCONFIG_DE
1b3c0 46 45 4e 53 49 56 45 20 6f 70 74 69 6f 6e 20 61  FENSIVE option a
1b3d0 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63  ctivates or deac
1b3e0 74 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22  tivates the.** "
1b3f0 64 65 66 65 6e 73 69 76 65 22 20 66 6c 61 67 20  defensive" flag 
1b400 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
1b410 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e  onnection.  When
1b420 20 74 68 65 20 64 65 66 65 6e 73 69 76 65 0a 2a   the defensive.*
1b430 2a 20 66 6c 61 67 20 69 73 20 65 6e 61 62 6c 65  * flag is enable
1b440 64 2c 20 6c 61 6e 67 75 61 67 65 20 66 65 61 74  d, language feat
1b450 75 72 65 73 20 74 68 61 74 20 61 6c 6c 6f 77 20  ures that allow 
1b460 6f 72 64 69 6e 61 72 79 20 53 51 4c 20 74 6f 20  ordinary SQL to 
1b470 0a 2a 2a 20 64 65 6c 69 62 65 72 61 74 65 6c 79  .** deliberately
1b480 20 63 6f 72 72 75 70 74 20 74 68 65 20 64 61 74   corrupt the dat
1b490 61 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 64  abase file are d
1b4a0 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20 64 69  isabled.  The di
1b4b0 73 61 62 6c 65 64 0a 2a 2a 20 66 65 61 74 75 72  sabled.** featur
1b4c0 65 73 20 69 6e 63 6c 75 64 65 20 62 75 74 20 61  es include but a
1b4d0 72 65 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 74  re not limited t
1b4e0 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a  o the following:
1b4f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1b500 20 54 68 65 20 5b 50 52 41 47 4d 41 20 77 72 69   The [PRAGMA wri
1b510 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d 4f 4e 5d  table_schema=ON]
1b520 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c   statement..** <
1b530 6c 69 3e 20 57 72 69 74 65 73 20 74 6f 20 74 68  li> Writes to th
1b540 65 20 5b 73 71 6c 69 74 65 5f 64 62 70 61 67 65  e [sqlite_dbpage
1b550 5d 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  ] virtual table.
1b560 0a 2a 2a 20 3c 6c 69 3e 20 44 69 72 65 63 74 20  .** <li> Direct 
1b570 77 72 69 74 65 73 20 74 6f 20 5b 73 68 61 64 6f  writes to [shado
1b580 77 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 3c 2f  w tables]..** </
1b590 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20  ul>.** </dd>.** 
1b5a0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
1b5b0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1b5c0 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20  _MAINDBNAME     
1b5d0 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63         1000 /* c
1b5e0 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64  onst char* */.#d
1b5f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1b600 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
1b610 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31              1001
1b620 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
1b630 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
1b640 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1b650 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20  BLE_FKEY        
1b660 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69     1002 /* int i
1b670 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1b680 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1b690 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20  NABLE_TRIGGER   
1b6a0 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74       1003 /* int
1b6b0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1b6c0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1b6d0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
1b6e0 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69  ENIZER 1004 /* i
1b6f0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1b700 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1b710 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
1b720 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a  XTENSION 1005 /*
1b730 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1b740 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1b750 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f  NFIG_NO_CKPT_ON_
1b760 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20  CLOSE      1006 
1b770 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
1b780 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1b790 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50  CONFIG_ENABLE_QP
1b7a0 53 47 20 20 20 20 20 20 20 20 20 20 20 31 30 30  SG           100
1b7b0 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  7 /* int int* */
1b7c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b7d0 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52  DBCONFIG_TRIGGER
1b7e0 5f 45 51 50 20 20 20 20 20 20 20 20 20 20 20 31  _EQP           1
1b7f0 30 30 38 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  008 /* int int* 
1b800 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b810 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45 54  E_DBCONFIG_RESET
1b820 5f 44 41 54 41 42 41 53 45 20 20 20 20 20 20 20  _DATABASE       
1b830 20 31 30 30 39 20 2f 2a 20 69 6e 74 20 69 6e 74   1009 /* int int
1b840 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1b850 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44 45 46  ITE_DBCONFIG_DEF
1b860 45 4e 53 49 56 45 20 20 20 20 20 20 20 20 20 20  ENSIVE          
1b870 20 20 20 31 30 31 30 20 2f 2a 20 69 6e 74 20 69     1010 /* int i
1b880 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1b890 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d  QLITE_DBCONFIG_M
1b8a0 41 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AX              
1b8b0 20 20 20 20 20 31 30 31 30 20 2f 2a 20 4c 61 72       1010 /* Lar
1b8c0 67 65 73 74 20 44 42 43 4f 4e 46 49 47 20 2a 2f  gest DBCONFIG */
1b8d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b8e0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
1b8f0 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
1b900 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54  ult Codes.** MET
1b910 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1b920 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b930 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
1b940 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
1b950 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
1b960 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
1b970 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1b980 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
1b990 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
1b9a0 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
1b9b0 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
1b9c0 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
1b9d0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
1b9e0 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
1b9f0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1ba00 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
1ba10 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
1ba20 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
1ba30 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
1ba40 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f  t Rowid.** METHO
1ba50 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1ba60 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
1ba70 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
1ba80 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
1ba90 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
1baa0 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
1bab0 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
1bac0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
1bad0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
1bae0 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
1baf0 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
1bb00 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
1bb10 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
1bb20 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
1bb30 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
1bb40 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
1bb50 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
1bb60 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
1bb70 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
1bb80 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
1bb90 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
1bba0 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
1bbb0 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
1bbc0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
1bbd0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
1bbe0 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
1bbf0 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
1bc00 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
1bc10 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1bc20 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
1bc30 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72  erface usually r
1bc40 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
1bc50 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73  d] of.** the mos
1bc60 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
1bc70 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
1bc80 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
1bc90 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
1bca0 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
1bcb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
1bcc0 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
1bcd0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
1bce0 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  bles are not.** 
1bcf0 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f  recorded. ^If no
1bd00 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
1bd10 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
1bd20 20 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65   tables have eve
1bd30 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f  r occurred .** o
1bd40 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1bd50 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65  onnection D, the
1bd60 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  n sqlite3_last_i
1bd70 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72  nsert_rowid(D) r
1bd80 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e  eturns .** zero.
1bd90 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61  .**.** As well a
1bda0 73 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f  s being set auto
1bdb0 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77  matically as row
1bdc0 73 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69  s are inserted i
1bdd0 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  nto database.** 
1bde0 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75  tables, the valu
1bdf0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
1be00 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
1be10 62 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c  be set explicitl
1be20 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  y by.** [sqlite3
1be30 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1be40 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20  _rowid()].**.** 
1be50 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62  Some virtual tab
1be60 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
1be70 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f  ns may INSERT ro
1be80 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ws into rowid ta
1be90 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20  bles as.** part 
1bea0 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20  of committing a 
1beb0 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67  transaction (e.g
1bec0 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  . to flush data 
1bed0 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d  accumulated in m
1bee0 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b  emory.** to disk
1bef0 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20  ). In this case 
1bf00 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1bf10 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
1bf20 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77  n return the row
1bf30 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  id.** associated
1bf40 20 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65   with these inte
1bf50 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72  rnal INSERT oper
1bf60 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65  ations, which le
1bf70 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74  ads to .** unint
1bf80 75 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20  uitive results. 
1bf90 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
1bfa0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68  plementations th
1bfb0 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72  at do write to r
1bfc0 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69  owid.** tables i
1bfd0 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61  n this way can a
1bfe0 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65  void this proble
1bff0 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74  m by restoring t
1c000 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20  he original .** 
1c010 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e  rowid value usin
1c020 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  g [sqlite3_set_l
1c030 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1c040 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72  ()] before retur
1c050 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c  ning .** control
1c060 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a   to the user..**
1c070 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
1c080 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
1c090 69 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65  in a trigger the
1c0a0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
1c0b0 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ill .** return t
1c0c0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
1c0d0 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61  e inserted row a
1c0e0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
1c0f0 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e  igger is .** run
1c100 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74  ning. Once the t
1c110 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
1c120 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
1c130 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
1c140 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
1c150 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
1c160 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
1c170 69 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e  igger was fired.
1c180 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
1c190 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
1c1a0 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
1c1b0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
1c1c0 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
1c1d0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
1c1e0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
1c1f0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
1c200 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
1c210 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
1c220 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
1c230 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
1c240 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
1c250 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
1c260 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
1c270 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
1c280 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1c290 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
1c2a0 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
1c2b0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
1c2c0 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
1c2d0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
1c2e0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
1c2f0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
1c300 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
1c310 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
1c320 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
1c330 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
1c340 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
1c350 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
1c360 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
1c370 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
1c380 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
1c390 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
1c3a0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1c3b0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1c3c0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
1c3d0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
1c3e0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
1c3f0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
1c400 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
1c410 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
1c420 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
1c430 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
1c440 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
1c450 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
1c460 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
1c470 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
1c480 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
1c490 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
1c4a0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1c4b0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1c4c0 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
1c4d0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
1c4e0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
1c4f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
1c500 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
1c510 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1c520 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
1c530 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
1c540 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
1c550 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1c560 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
1c570 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1c580 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
1c590 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1c5a0 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
1c5b0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
1c5c0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
1c5d0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
1c5e0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
1c5f0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
1c600 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1c610 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1c620 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
1c630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c640 46 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20  F: Set the Last 
1c650 49 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c  Insert Rowid val
1c660 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ue..** METHOD: s
1c670 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
1c680 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73   sqlite3_set_las
1c690 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1c6a0 2c 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f  , R) method allo
1c6b0 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ws the applicati
1c6c0 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65  on to.** set the
1c6d0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1c6e0 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  by calling sqlit
1c6f0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1c700 6f 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a  owid(D) to R .**
1c710 20 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69   without inserti
1c720 6e 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68  ng a row into th
1c730 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76  e database..*/.v
1c740 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
1c750 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1c760 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74  d(sqlite3*,sqlit
1c770 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  e3_int64);../*.*
1c780 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
1c790 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
1c7a0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1c7b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1c7c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1c7d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1c7e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1c7f0 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
1c800 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
1c810 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
1c820 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
1c830 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1c840 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
1c850 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
1c860 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c870 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
1c880 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1c890 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
1c8a0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1c8b0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1c8c0 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
1c8d0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
1c8e0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
1c8f0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
1c900 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
1c910 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
1c920 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
1c930 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1c940 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
1c950 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
1c960 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
1c970 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
1c980 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
1c990 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
1c9a0 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
1c9b0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
1c9c0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1c9d0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1c9e0 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
1c9f0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
1ca00 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
1ca10 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
1ca20 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
1ca30 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
1ca40 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1ca50 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
1ca60 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1ca70 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
1ca80 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
1ca90 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1caa0 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
1cab0 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
1cac0 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
1cad0 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
1cae0 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
1caf0 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
1cb00 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
1cb10 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
1cb20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
1cb30 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
1cb40 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1cb50 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
1cb60 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
1cb70 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
1cb80 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
1cb90 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
1cba0 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
1cbb0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1cbc0 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
1cbd0 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
1cbe0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
1cbf0 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
1cc00 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
1cc10 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
1cc20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1cc30 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
1cc40 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
1cc50 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
1cc60 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1cc70 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
1cc80 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1cc90 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
1cca0 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
1ccb0 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
1ccc0 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
1ccd0 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
1cce0 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
1ccf0 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
1cd00 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
1cd10 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
1cd20 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
1cd30 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
1cd40 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
1cd50 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
1cd60 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1cd70 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1cd80 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
1cd90 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
1cda0 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
1cdb0 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
1cdc0 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
1cdd0 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
1cde0 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
1cdf0 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
1ce00 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1ce10 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
1ce20 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
1ce30 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
1ce40 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
1ce50 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
1ce60 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
1ce70 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
1ce80 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
1ce90 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
1cea0 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
1ceb0 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
1cec0 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
1ced0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1cee0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1cef0 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
1cf00 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
1cf10 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
1cf20 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
1cf30 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
1cf40 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
1cf50 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
1cf60 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
1cf70 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
1cf80 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1cf90 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
1cfa0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1cfb0 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
1cfc0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1cfd0 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
1cfe0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
1cff0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1d000 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1d010 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
1d020 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  trigger..**.** I
1d030 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1d040 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1d050 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1d060 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d070 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1d080 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1d090 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1d0a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1d0b0 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
1d0c0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1d0d0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20  aningful..**.** 
1d0e0 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c  See also:.** <ul
1d0f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73  >.** <li> the [s
1d100 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1d110 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1d120 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63  e.** <li> the [c
1d130 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1d140 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65  gma].** <li> the
1d150 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1d160 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69  function].** <li
1d170 3e 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73  > the [data_vers
1d180 69 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c  ion pragma].** <
1d190 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ul>.*/.int sqli
1d1a0 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
1d1b0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1d1c0 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
1d1d0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
1d1e0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
1d1f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1d200 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
1d210 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20  turns the total 
1d220 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69  number of rows i
1d230 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65  nserted, modifie
1d240 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d or.** deleted 
1d250 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c  by all [INSERT],
1d260 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
1d270 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
1d280 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69   completed.** si
1d290 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nce the database
1d2a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20   connection was 
1d2b0 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e  opened, includin
1d2c0 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64  g those executed
1d2d0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74   as.** part of t
1d2e0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e  rigger programs.
1d2f0 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
1d300 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
1d310 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64  L statement.** d
1d320 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74  oes not affect t
1d330 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1d340 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
1d350 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a  al_changes()..**
1d360 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61   .** ^Changes ma
1d370 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66  de as part of [f
1d380 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
1d390 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64  ns] are included
1d3a0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74   in the.** count
1d3b0 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65  , but those made
1d3c0 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c   as part of REPL
1d3d0 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  ACE constraint r
1d3e0 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a  esolution are.**
1d3f0 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74   not. ^Changes t
1d400 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
1d410 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
1d420 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
1d430 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74  gers .** are not
1d440 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
1d450 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  The [sqlite3_tot
1d460 61 6c 5f 63 68 61 6e 67 65 73 28 44 29 5d 20 69  al_changes(D)] i
1d470 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65  nterface only re
1d480 70 6f 72 74 73 20 74 68 65 20 6e 75 6d 62 65 72  ports the number
1d490 0a 2a 2a 20 6f 66 20 72 6f 77 73 20 74 68 61 74  .** of rows that
1d4a0 20 63 68 61 6e 67 65 64 20 64 75 65 20 74 6f 20   changed due to 
1d4b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 72 75  SQL statement ru
1d4c0 6e 20 61 67 61 69 6e 73 74 20 64 61 74 61 62 61  n against databa
1d4d0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
1d4e0 20 44 2e 20 20 41 6e 79 20 63 68 61 6e 67 65 73   D.  Any changes
1d4f0 20 62 79 20 6f 74 68 65 72 20 64 61 74 61 62 61   by other databa
1d500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61  se connections a
1d510 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 54  re ignored..** T
1d520 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73  o detect changes
1d530 20 61 67 61 69 6e 73 74 20 61 20 64 61 74 61 62   against a datab
1d540 61 73 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f 74  ase file from ot
1d550 68 65 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  her database.** 
1d560 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65 20  connections use 
1d570 74 68 65 20 5b 50 52 41 47 4d 41 20 64 61 74 61  the [PRAGMA data
1d580 5f 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e  _version] comman
1d590 64 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  d or the.** [SQL
1d5a0 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56  ITE_FCNTL_DATA_V
1d5b0 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f  ERSION] [file co
1d5c0 6e 74 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49  ntrol]..** .** I
1d5d0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1d5e0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1d5f0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1d600 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d610 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1d620 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1d630 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1d640 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
1d650 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
1d660 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1d670 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1d680 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a  **.** See also:.
1d690 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1d6a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
1d6b0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1d6c0 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63  e.** <li> the [c
1d6d0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1d6e0 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65  gma].** <li> the
1d6f0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1d700 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69  function].** <li
1d710 3e 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73  > the [data_vers
1d720 69 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c  ion pragma].** <
1d730 6c 69 3e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  li> the [SQLITE_
1d740 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49  FCNTL_DATA_VERSI
1d750 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  ON] [file contro
1d760 6c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  l].** </ul>.*/.i
1d770 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
1d780 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1d790 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1d7a0 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
1d7b0 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
1d7c0 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ery.** METHOD: s
1d7d0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1d7e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
1d7f0 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
1d800 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1d810 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
1d820 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
1d830 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
1d840 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
1d850 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
1d860 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
1d870 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
1d880 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
1d890 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
1d8a0 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
1d8b0 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
1d8c0 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
1d8d0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
1d8e0 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
1d8f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
1d900 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1d910 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
1d920 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
1d930 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
1d940 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
1d950 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
1d960 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
1d970 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
1d980 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1d990 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1d9a0 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
1d9b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
1d9c0 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
1d9d0 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
1d9e0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
1d9f0 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
1da00 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
1da10 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1da20 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
1da30 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
1da40 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
1da50 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
1da60 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
1da70 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
1da80 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
1da90 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
1daa0 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
1dab0 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
1dac0 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
1dad0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
1dae0 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
1daf0 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
1db00 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
1db10 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
1db20 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
1db30 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
1db40 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
1db50 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
1db60 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
1db70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
1db80 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
1db90 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
1dba0 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
1dbb0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
1dbc0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
1dbd0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1dbe0 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
1dbf0 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
1dc00 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1dc10 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1dc20 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
1dc30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1dc40 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
1dc50 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
1dc60 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1dc70 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1dc80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1dc90 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
1dca0 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
1dcb0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
1dcc0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
1dcd0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
1dce0 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
1dcf0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
1dd00 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1dd10 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1dd20 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
1dd30 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1dd40 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1dd50 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
1dd60 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
1dd70 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
1dd80 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
1dd90 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
1dda0 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
1ddb0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1ddc0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
1ddd0 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
1dde0 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
1ddf0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1de00 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
1de10 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
1de20 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
1de30 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1de40 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1de50 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1de60 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
1de70 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  rns..*/.void sql
1de80 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
1de90 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1dea0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
1deb0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
1dec0 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
1ded0 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
1dee0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
1def0 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
1df00 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
1df10 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
1df20 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
1df30 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
1df40 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
1df50 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1df60 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
1df70 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
1df80 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
1df90 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
1dfa0 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
1dfb0 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
1dfc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1dfd0 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
1dfe0 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
1dff0 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
1e000 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1e010 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
1e020 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
1e030 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
1e040 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
1e050 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
1e060 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
1e070 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
1e080 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
1e090 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
1e0a0 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
1e0b0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
1e0c0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
1e0d0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
1e0e0 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
1e0f0 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
1e100 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
1e110 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
1e120 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
1e130 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
1e140 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
1e150 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
1e160 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
1e170 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
1e180 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
1e190 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
1e1a0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
1e1b0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
1e1c0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
1e1d0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
1e1e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1e1f0 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
1e200 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
1e210 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
1e220 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e230 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
1e240 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
1e250 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
1e260 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
1e270 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
1e280 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
1e290 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
1e2a0 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
1e2b0 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
1e2c0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
1e2d0 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
1e2e0 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
1e2f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
1e300 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
1e310 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
1e320 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1e330 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
1e340 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
1e350 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
1e360 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
1e370 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1e380 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
1e390 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
1e3a0 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
1e3b0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
1e3c0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
1e3d0 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
1e3e0 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
1e3f0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1e400 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
1e410 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
1e420 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
1e430 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1e440 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
1e450 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
1e460 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
1e470 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
1e480 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1e490 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1e4a0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1e4b0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1e4c0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
1e4d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1e4e0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
1e4f0 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
1e500 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
1e510 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1e520 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
1e530 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
1e540 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
1e550 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
1e560 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
1e570 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f   Errors.** KEYWO
1e580 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c  RDS: {busy-handl
1e590 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75  er callback} {bu
1e5a0 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d  sy handler}.** M
1e5b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1e5c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e5d0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
1e5e0 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
1e5f0 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
1e600 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
1e610 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1e620 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
1e630 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
1e640 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
1e650 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
1e660 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
1e670 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
1e680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e690 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
1e6a0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
1e6b0 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
1e6c0 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
1e6d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
1e6e0 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
1e6f0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
1e700 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
1e710 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1e720 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
1e730 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1e740 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
1e750 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1e760 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
1e770 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
1e780 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1e790 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
1e7a0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
1e7b0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
1e7c0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
1e7d0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
1e7e0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
1e7f0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1e800 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
1e810 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1e820 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1e830 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1e840 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1e850 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
1e860 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
1e870 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1e880 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1e890 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
1e8a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
1e8b0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1e8c0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
1e8d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
1e8e0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
1e8f0 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
1e900 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72   been invoked pr
1e910 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65  eviously for the
1e920 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
1e930 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
1e940 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
1e950 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
1e960 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
1e970 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
1e980 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
1e990 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
1e9a0 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65  LITE_BUSY] is re
1e9b0 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
1e9c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
1e9d0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
1e9e0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1e9f0 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
1ea00 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
1ea10 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
1ea20 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
1ea30 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
1ea40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
1ea50 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
1ea60 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
1ea70 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
1ea80 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
1ea90 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
1eaa0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
1eab0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
1eac0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
1ead0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
1eae0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
1eaf0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
1eb00 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
1eb10 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
1eb20 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
1eb30 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  ].** to the appl
1eb40 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20  ication instead 
1eb50 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
1eb60 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1eb70 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
1eb80 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
1eb90 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
1eba0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
1ebb0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
1ebc0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
1ebd0 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
1ebe0 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
1ebf0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
1ec00 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
1ec10 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
1ec20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
1ec30 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
1ec40 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
1ec50 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1ec60 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
1ec70 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
1ec80 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1ec90 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
1eca0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
1ecb0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
1ecc0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1ecd0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
1ece0 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
1ecf0 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
1ed00 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1ed10 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
1ed20 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
1ed30 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
1ed40 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
1ed50 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
1ed60 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
1ed70 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
1ed80 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
1ed90 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
1eda0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
1edb0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
1edc0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
1edd0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1ede0 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
1edf0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1ee00 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1ee10 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s NULL..**.** ^(
1ee20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1ee30 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1ee40 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
1ee50 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
1ee60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ee70 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
1ee80 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
1ee90 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
1eea0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
1eeb0 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
1eec0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1eed0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1eee0 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61  ()].** or evalua
1eef0 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73  ting [PRAGMA bus
1ef00 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c  y_timeout=N] wil
1ef10 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  l change the.** 
1ef20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64  busy handler and
1ef30 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20   thus clear any 
1ef40 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62  previously set b
1ef50 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
1ef60 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
1ef70 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
1ef80 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
1ef90 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
1efa0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1efb0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1efc0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1efd0 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65  andler.  In othe
1efe0 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20  r words,.** the 
1eff0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1f000 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20  not reentrant.  
1f010 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1f020 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1f030 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1f040 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1f050 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1f060 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1f070 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1f080 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1f090 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1f0a0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1f0b0 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
1f0c0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1f0d0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e  dler(sqlite3*,in
1f0e0 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
1f0f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1f100 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
1f110 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d  usy Timeout.** M
1f120 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1f130 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1f140 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
1f150 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
1f160 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
1f170 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
1f180 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
1f190 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
1f1a0 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
1f1b0 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
1f1c0 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
1f1d0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
1f1e0 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
1f1f0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1f200 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
1f210 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
1f220 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
1f230 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1f240 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1f250 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
1f260 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
1f270 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
1f280 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
1f290 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
1f2a0 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  USY]..**.** ^Cal
1f2b0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
1f2c0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
1f2d0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
1f2e0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
1f2f0 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
1f300 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
1f310 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1f320 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1f330 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
1f340 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
1f350 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1f360 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67  ection] at any g
1f370 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
1f380 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
1f390 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
1f3a0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
1f3b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1f3c0 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
1f3d0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
1f3e0 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
1f3f0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1f400 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
1f410 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
1f420 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1f430 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  eout].*/.int sql
1f440 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1f450 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1f460 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
1f470 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
1f480 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
1f490 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
1f4a0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1f4b0 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  3.**.** This is 
1f4c0 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
1f4d0 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
1f4e0 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
1f4f0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1f500 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
1f510 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
1f520 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
1f530 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
1f540 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
1f550 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
1f560 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
1f570 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
1f580 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
1f590 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
1f5a0 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
1f5b0 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
1f5c0 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
1f5d0 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
1f5e0 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
1f5f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
1f600 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
1f610 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
1f620 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
1f630 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
1f640 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
1f650 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
1f660 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
1f670 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
1f680 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
1f690 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
1f6a0 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
1f6b0 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
1f6c0 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
1f6d0 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
1f6e0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1f6f0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
1f700 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
1f710 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1f720 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
1f730 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
1f740 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
1f750 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
1f760 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
1f770 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
1f780 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1f790 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
1f7a0 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
1f7b0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
1f7c0 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
1f7d0 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
1f7e0 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
1f7f0 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
1f800 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
1f810 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
1f820 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
1f830 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
1f840 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1f850 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
1f860 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
1f870 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
1f880 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
1f890 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1f8a0 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
1f8b0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
1f8c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f8d0 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
1f8e0 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
1f8f0 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
1f900 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
1f910 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
1f920 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
1f930 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
1f940 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1f950 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
1f960 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
1f970 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
1f980 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
1f990 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
1f9a0 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
1f9b0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1f9c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1f9d0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
1f9e0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
1f9f0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
1fa00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1fa10 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
1fa20 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
1fa30 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
1fa40 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
1fa50 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
1fa60 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
1fa70 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1fa80 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
1fa90 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
1faa0 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
1fab0 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
1fac0 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
1fad0 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
1fae0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
1faf0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
1fb00 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
1fb10 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
1fb20 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
1fb30 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
1fb40 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1fb50 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1fb60 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1fb70 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
1fb80 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1fb90 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
1fba0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1fbb0 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
1fbc0 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
1fbd0 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
1fbe0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
1fbf0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
1fc00 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
1fc10 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1fc20 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
1fc30 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1fc40 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
1fc50 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1fc60 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
1fc70 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1fc80 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1fc90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
1fca0 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
1fcb0 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
1fcc0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
1fcd0 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
1fce0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1fcf0 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
1fd00 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
1fd10 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
1fd20 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
1fd30 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1fd40 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
1fd50 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
1fd60 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
1fd70 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
1fd80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1fd90 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1fda0 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
1fdb0 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
1fdc0 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
1fdd0 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
1fde0 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
1fdf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1fe00 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
1fe10 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
1fe20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
1fe30 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
1fe40 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
1fe50 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1fe60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
1fe70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
1fe80 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
1fe90 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
1fea0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
1feb0 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
1fec0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
1fed0 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
1fee0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1fef0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
1ff00 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
1ff10 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
1ff20 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
1ff30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1ff40 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
1ff50 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
1ff60 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
1ff70 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
1ff80 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
1ff90 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1ffa0 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
1ffb0 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
1ffc0 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
1ffd0 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
1ffe0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
1fff0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
20000 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
20010 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
20020 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
20030 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
20040 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
20050 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
20060 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
20070 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
20080 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
20090 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
200a0 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
200b0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
200c0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
200d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
200e0 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  msg()]..*/.int s
200f0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
20100 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
20110 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
20120 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
20130 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
20140 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
20150 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
20160 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
20170 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
20180 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
20190 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
201a0 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
201b0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
201c0 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
201d0 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
201e0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
201f0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
20200 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
20210 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
20220 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
20230 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
20240 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
20250 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
20260 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
20270 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
20280 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
20290 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
202a0 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
202b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
202c0 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
202d0 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
202e0 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
202f0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
20300 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
20310 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68  C library..** Th
20320 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64  ese routines und
20330 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20  erstand most of 
20340 74 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d 61  the common forma
20350 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72  tting options fr
20360 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
20370 72 64 20 6c 69 62 72 61 72 79 20 70 72 69 6e 74  rd library print
20380 66 28 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d  f() .** plus som
20390 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e  e additional non
203a0 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74  -standard format
203b0 73 20 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20 5b  s ([%q], [%Q], [
203c0 25 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e 0a  %w], and [%z])..
203d0 2a 2a 20 53 65 65 20 74 68 65 20 5b 62 75 69 6c  ** See the [buil
203e0 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 20 64  t-in printf()] d
203f0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
20400 20 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20   details..**.** 
20410 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
20420 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
20430 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
20440 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
20450 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
20460 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
20470 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
20480 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a 2a  _malloc64()]..**
20490 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
204a0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
204b0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
204c0 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
204d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
204e0 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
204f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
20500 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
20510 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
20520 6f 63 36 34 28 29 5d 20 69 73 20 75 6e 61 62 6c  oc64()] is unabl
20530 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
20540 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
20550 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
20560 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
20570 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
20580 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
20590 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
205a0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
205b0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
205c0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
205d0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
205e0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
205f0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
20600 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
20610 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
20620 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
20630 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
20640 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
20650 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
20660 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
20670 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
20680 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
20690 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
206a0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
206b0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
206c0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
206d0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
206e0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
206f0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
20700 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
20710 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
20720 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
20730 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
20740 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
20750 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
20760 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
20770 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
20780 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
20790 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
207a0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
207b0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
207c0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
207d0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
207e0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
207f0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
20800 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
20810 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
20820 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
20830 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
20840 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
20850 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
20860 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
20870 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
20880 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
20890 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
208a0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
208b0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
208c0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
208d0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
208e0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
208f0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
20900 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
20910 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
20920 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
20930 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
20940 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
20950 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
20960 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
20970 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
20980 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
20990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
209a0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
209b0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
209c0 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
209d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
209e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ()..**.** See al
209f0 73 6f 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20 70  so:  [built-in p
20a00 72 69 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e 74  rintf()], [print
20a10 66 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  f() SQL function
20a20 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ].*/.char *sqlit
20a30 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
20a40 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
20a50 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
20a60 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
20a70 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
20a80 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
20a90 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
20aa0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63  t char*, ...);.c
20ab0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
20ac0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
20ad0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
20ae0 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
20af0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
20b00 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
20b10 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
20b20 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
20b30 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
20b40 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
20b50 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
20b60 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
20b70 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
20b80 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
20b90 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
20ba0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
20bb0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
20bc0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
20bd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
20be0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
20bf0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
20c00 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
20c10 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
20c20 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
20c30 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
20c40 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
20c50 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
20c60 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
20c70 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
20c80 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
20c90 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
20ca0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
20cb0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
20cc0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
20cd0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
20ce0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
20cf0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
20d00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
20d10 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
20d20 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
20d30 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
20d40 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
20d50 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
20d60 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
20d70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
20d80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
20d90 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f  3_malloc64(N) ro
20da0 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74  utine works just
20db0 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33   like.** sqlite3
20dc0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70  _malloc(N) excep
20dd0 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75  t that N is an u
20de0 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69  nsigned 64-bit i
20df0 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
20e00 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32  * of a signed 32
20e10 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  -bit integer..**
20e20 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
20e30 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
20e40 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
20e50 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
20e60 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
20e70 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
20e80 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
20e90 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
20ea0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
20eb0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
20ec0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
20ed0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
20ee0 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
20ef0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
20f00 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
20f10 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
20f20 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
20f30 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
20f40 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
20f50 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
20f60 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
20f70 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
20f80 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
20f90 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
20fa0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
20fb0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
20fc0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
20fd0 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
20fe0 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
20ff0 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
21000 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
21010 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
21020 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
21030 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
21040 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
21050 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
21060 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
21070 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
21080 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
21090 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
210a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
210b0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  lloc()..**.** ^T
210c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
210d0 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  oc(X,N) interfac
210e0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
210f0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
21100 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
21110 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61  n X to be at lea
21120 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  st N bytes..** ^
21130 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  If the X paramet
21140 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
21150 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73  alloc(X,N).** is
21160 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21170 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
21180 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
21190 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
211a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a  ite3_malloc(N)..
211b0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72  ** ^If the N par
211c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
211d0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
211e0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
211f0 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
21200 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
21210 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
21220 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
21230 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73  3_free(X)..** ^s
21240 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
21250 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ,N) returns a po
21260 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
21270 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
21280 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
21290 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
212a0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
212b0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76  ent memory is av
212c0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
212d0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
212e0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
212f0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
21300 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
21310 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
21320 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
21330 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
21340 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
21350 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
21360 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
21370 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
21380 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
21390 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
213a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
213b0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
213c0 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c  d N is positive,
213d0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69   then the.** pri
213e0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
213f0 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
21400 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
21410 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e  ealloc64(X,N) in
21420 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74  terfaces works t
21430 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
21440 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
21450 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
21460 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73   is a 64-bit uns
21470 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e  igned integer in
21480 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32  stead.** of a 32
21490 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
214a0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58  ger..**.** ^If X
214b0 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   is a memory all
214c0 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73  ocation previous
214d0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
214e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
214f0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
21500 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65  lloc64(), sqlite
21510 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20  3_realloc(), or 
21520 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
21530 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  4(), then.** sql
21540 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
21550 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
21560 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c  f that memory al
21570 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65  location in byte
21580 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  s..** ^The value
21590 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
215a0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69  ite3_msize(X) mi
215b0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
215c0 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  an the number.**
215d0 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73   of bytes reques
215e0 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61  ted when X was a
215f0 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58  llocated.  ^If X
21600 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
21610 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  er then.** sqlit
21620 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
21630 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20  rns zero.  If X 
21640 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68  points to someth
21650 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a  ing that is not.
21660 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ** the beginning
21670 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
21680 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20  ation, or if it 
21690 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d  points to a form
216a0 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65  erly.** valid me
216b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
216c0 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65  that has now bee
216d0 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68  n freed, then th
216e0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
216f0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
21700 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  ) is undefined a
21710 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d  nd possibly harm
21720 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ful..**.** ^The 
21730 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
21740 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
21750 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  c(), sqlite3_rea
21760 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
21770 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61  e3_malloc64(), a
21780 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
21790 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77  oc64().** is alw
217a0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
217b0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
217c0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
217d0 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
217e0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
217f0 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
21800 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
21810 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
21820 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
21830 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
21840 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
21850 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
21860 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
21870 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
21880 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
21890 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
218a0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
218b0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
218c0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
218d0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
218e0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
218f0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
21900 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
21910 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
21920 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
21930 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
21940 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
21950 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
21960 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
21970 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
21980 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
21990 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
219a0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
219b0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
219c0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
219d0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
219e0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
219f0 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
21a00 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
21a10 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
21a20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
21a30 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
21a40 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
21a50 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
21a60 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
21a70 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
21a80 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
21a90 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
21aa0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
21ab0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
21ac0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
21ad0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
21ae0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
21af0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
21b00 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
21b10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
21b20 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
21b30 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
21b40 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
21b50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
21b60 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
21b70 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
21b80 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
21b90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
21ba0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
21bb0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
21bc0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
21bd0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
21be0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
21bf0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
21c00 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
21c10 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
21c20 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
21c30 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
21c40 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
21c50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
21c60 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
21c70 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
21c80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
21c90 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69  loc64(sqlite3_ui
21ca0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  nt64);.void *sql
21cb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
21cc0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  d*, int);.void *
21cd0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
21ce0 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  4(void*, sqlite3
21cf0 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  _uint64);.void s
21d00 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
21d10 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74  *);.sqlite3_uint
21d20 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  64 sqlite3_msize
21d30 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
21d40 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
21d50 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
21d60 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
21d70 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
21d80 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
21d90 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
21da0 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
21db0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
21dc0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
21dd0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
21de0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
21df0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
21e00 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
21e10 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
21e20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
21e30 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
21e40 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
21e50 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
21e60 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
21e70 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
21e80 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
21e90 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
21ea0 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
21eb0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
21ec0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
21ed0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
21ee0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
21ef0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
21f00 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
21f10 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
21f20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
21f30 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
21f40 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
21f50 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
21f60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
21f70 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
21f80 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
21f90 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
21fa0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
21fb0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
21fc0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
21fd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
21fe0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
21ff0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
22000 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
22010 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
22020 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
22030 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
22040 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
22050 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
22060 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
22070 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
22080 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
22090 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
220a0 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
220b0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
220c0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
220d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
220e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
220f0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
22100 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
22110 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
22120 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
22130 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
22140 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
22150 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
22160 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
22170 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
22180 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
22190 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
221a0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
221b0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
221c0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
221d0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
221e0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
221f0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
22200 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
22210 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
22220 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
22230 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
22240 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
22250 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
22260 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
22270 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
22280 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
22290 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
222a0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
222b0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
222c0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
222d0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
222e0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
222f0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
22300 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
22310 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
22320 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
22330 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
22340 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
22350 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
22360 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
22370 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
22380 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
22390 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
223a0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
223b0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
223c0 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  er P..** ^The P 
223d0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
223e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
223f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
22400 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
22410 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
22420 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
22430 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
22440 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
22450 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20  n one or a NULL 
22460 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74  pointer for P, t
22470 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a  hen the PRNG is.
22480 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  ** seeded using 
22490 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
224a0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
224b0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
224c0 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  of.** the defaul
224d0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
224e0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
224f0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
22500 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
22510 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
22520 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20  r more and a.** 
22530 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20  non-NULL P then 
22540 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
22550 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
22560 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
22570 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
22580 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
22590 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
225a0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
225b0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
225c0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
225d0 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
225e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
225f0 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
22600 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
22610 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
22620 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52  qlite3.** KEYWOR
22630 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20  DS: {authorizer 
22640 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20  callback}.**.** 
22650 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
22660 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
22670 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
22680 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
22690 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
226a0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
226b0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
226c0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
226d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
226e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
226f0 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
22700 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
22710 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
22720 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
22730 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
22740 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22750 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
22760 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
22770 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
22780 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69  pare16()], [sqli
22790 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
227a0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  ()],.** and [sql
227b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
227c0 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  3()].  ^At vario
227d0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
227e0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
227f0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
22800 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
22810 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
22820 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
22830 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
22840 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
22850 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
22860 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
22870 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
22880 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
22890 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
228a0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
228b0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
228c0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
228d0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
228e0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
228f0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
22900 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
22910 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
22920 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
22930 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
22940 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
22950 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
22960 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
22970 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
22980 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
22990 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
229a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
229b0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
229c0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
229d0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
229e0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
229f0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
22a00 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
22a10 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
22a20 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
22a30 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
22a40 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
22a50 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
22a60 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
22a70 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
22a80 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
22a90 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
22aa0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
22ab0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
22ac0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
22ad0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
22ae0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
22af0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
22b00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22b10 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
22b20 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
22b30 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
22b40 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
22b50 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
22b60 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
22b70 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
22b80 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
22b90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
22ba0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
22bb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22bc0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
22bd0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
22be0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
22bf0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
22c00 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
22c10 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
22c20 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
22c30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
22c40 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
22c50 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
22c60 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
22c70 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
22c80 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
22c90 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
22ca0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
22cb0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
22cc0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
22cd0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74  callback are eit
22ce0 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  her NULL pointer
22cf0 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s or zero-termin
22d00 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ated strings.** 
22d10 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
22d20 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20  itional details 
22d30 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
22d40 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
22d50 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  d..** Applicatio
22d60 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62  ns must always b
22d70 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e  e prepared to en
22d80 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70  counter a NULL p
22d90 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a  ointer in any.**
22da0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74 68   of the third th
22db0 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 68 20  rough the sixth 
22dc0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
22dd0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e authorization 
22de0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
22df0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
22e00 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
22e10 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
22e20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
22e30 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
22e40 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
22e50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22e60 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
22e70 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
22e80 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
22e90 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
22ea0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
22eb0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
22ec0 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
22ed0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
22ee0 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
22ef0 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
22f00 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
22f10 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
22f20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
22f30 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
22f40 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
22f50 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
22f60 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61  able..** ^When a
22f70 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72 65   table is refere
22f80 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43  nced by a [SELEC
22f90 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e  T] but no column
22fa0 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65   values are.** e
22fb0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68  xtracted from th
22fc0 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78  at table (for ex
22fd0 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79  ample in a query
22fe0 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54   like.** "SELECT
22ff0 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74   count(*) FROM t
23000 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53  ab") then the [S
23010 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68  QLITE_READ] auth
23020 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
23030 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ** is invoked on
23040 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c  ce for that tabl
23050 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20  e with a column 
23060 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20  name that is an 
23070 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
23080 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
23090 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
230a0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
230b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
230c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
230d0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
230e0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
230f0 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
23100 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
23110 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
23120 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
23130 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
23140 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
23150 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
23160 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
23170 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23180 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
23190 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
231a0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
231b0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
231c0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
231d0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
231e0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
231f0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
23200 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
23210 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
23220 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
23230 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
23240 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
23250 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
23260 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
23270 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
23280 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
23290 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
232a0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
232b0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
232c0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
232d0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
232e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
232f0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
23300 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
23310 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
23320 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
23330 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
23340 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
23350 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
23360 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
23370 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
23380 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
23390 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
233a0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
233b0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
233c0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
233d0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
233e0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
233f0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
23400 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
23410 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
23420 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
23430 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
23440 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
23450 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
23460 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
23470 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
23480 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
23490 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
234a0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
234b0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
234c0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
234d0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
234e0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
234f0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
23500 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
23510 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
23520 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
23530 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
23540 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
23550 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
23560 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
23570 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
23580 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
23590 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
235a0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
235b0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
235c0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
235d0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
235e0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
235f0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
23600 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
23610 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
23620 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
23630 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
23640 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
23650 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
23660 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
23670 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
23680 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
23690 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
236a0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
236b0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
236c0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
236d0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
236e0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
236f0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
23700 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
23710 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
23720 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
23730 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
23740 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
23750 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
23760 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
23770 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
23780 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
23790 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
237a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
237b0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
237c0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
237d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
237e0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
237f0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
23800 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
23810 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
23820 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
23830 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
23840 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
23850 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
23860 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
23870 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
23880 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
23890 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
238a0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
238b0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
238c0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
238d0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
238e0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
238f0 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
23900 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
23910 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
23920 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
23930 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
23940 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
23950 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
23960 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
23970 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
23980 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
23990 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
239a0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
239b0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
239c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
239d0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
239e0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
239f0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
23a00 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
23a10 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
23a20 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
23a30 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
23a40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
23a50 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
23a60 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
23a70 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
23a80 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
23a90 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
23aa0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
23ab0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
23ac0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
23ad0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
23ae0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
23af0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
23b00 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
23b10 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
23b20 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
23b30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
23b40 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
23b50 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
23b60 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65  s a [conflict re
23b70 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a  solution mode].*
23b80 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  * returned from 
23b90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
23ba0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
23bb0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
23bc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
23bd0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
23be0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
23bf0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
23c00 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
23c10 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
23c20 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
23c30 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
23c40 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
23c50 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
23c60 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
23c70 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
23c80 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
23c90 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
23ca0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
23cb0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
23cc0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
23cd0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
23ce0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
23cf0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
23d00 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
23d10 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
23d20 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
23d30 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
23d40 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
23d50 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
23d60 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
23d70 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
23d80 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
23d90 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
23da0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
23db0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
23dc0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
23dd0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
23de0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
23df0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
23e00 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
23e10 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
23e20 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
23e30 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
23e40 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
23e50 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
23e60 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
23e70 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
23e80 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
23e90 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
23ea0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
23eb0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
23ec0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
23ed0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
23ee0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
23ef0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
23f00 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
23f10 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
23f20 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
23f30 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
23f40 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
23f50 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
23f60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
23f70 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
23f80 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
23f90 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
23fa0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
23fb0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
23fc0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
23fd0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
23fe0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
23ff0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
24000 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
24010 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
24020 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24030 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24040 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
24050 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
24060 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
24070 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
24080 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
24090 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
240a0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
240b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
240c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
240d0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
240e0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
240f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
24100 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24110 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
24120 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
24130 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
24140 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
24150 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24160 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
24170 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
24180 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
24190 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
241a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
241b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
241c0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
241d0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
241e0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
241f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24200 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
24210 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
24220 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
24230 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24240 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24250 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
24260 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
24270 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
24280 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24290 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
242a0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
242b0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
242c0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
242d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
242e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
242f0 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
24300 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
24310 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
24320 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24330 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24340 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
24350 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
24360 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
24370 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
24380 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
24390 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
243a0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
243b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
243c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
243d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
243e0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
243f0 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
24400 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
24410 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
24420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
24430 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
24440 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
24450 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
24460 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
24470 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
24480 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
24490 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
244a0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
244b0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
244c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
244d0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
244e0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
244f0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
24500 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
24510 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
24520 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
24530 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
24540 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
24550 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
24560 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
24570 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
24580 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
24590 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
245a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
245b0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
245c0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
245d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
245e0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
245f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24600 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
24610 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
24620 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
24630 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
24640 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
24650 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
24660 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
24670 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
24680 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
24690 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
246a0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
246b0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
246c0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
246d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
246e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
246f0 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
24700 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
24710 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
24720 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24730 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24740 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
24750 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
24760 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24770 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
24780 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24790 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
247a0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
247b0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
247c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
247d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
247e0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
247f0 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
24800 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
24810 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24820 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24830 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
24840 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
24850 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
24860 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
24870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
24880 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
24890 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
248a0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
248b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
248c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
248d0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
248e0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
248f0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
24900 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
24910 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
24920 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
24930 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
24940 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
24950 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
24960 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
24970 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
24980 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
24990 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
249a0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
249b0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
249c0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
249d0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
249e0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
249f0 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
24a00 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
24a10 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
24a20 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
24a30 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
24a40 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
24a50 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
24a60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
24a70 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
24a80 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
24a90 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45  SQLITE_RECURSIVE
24aa0 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20              33  
24ab0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
24ac0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24ad0 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41      */../*.** CA
24ae0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
24af0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
24b00 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
24b10 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
24b20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
24b30 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20  are deprecated. 
24b40 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
24b50 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74  _trace_v2()] int
24b60 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61  erface.** instea
24b70 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65  d of the routine
24b80 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65  s described here
24b90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
24ba0 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
24bb0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
24bc0 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
24bd0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
24be0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
24bf0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
24c00 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
24c10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
24c20 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
24c30 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
24c40 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
24c50 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
24c60 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
24c70 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
24c80 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
24c90 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
24ca0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
24cb0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
24cc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
24cd0 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
24ce0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
24cf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
24d00 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
24d10 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
24d20 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
24d30 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
24d40 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
24d50 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
24d60 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
24d70 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
24d80 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
24d90 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
24da0 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
24db0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
24dc0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
24dd0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
24de0 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  igger.)^.**.** T
24df0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
24e00 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
24e10 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
24e20 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
24e30 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e  limit.** the len
24e40 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  gth of [bound pa
24e50 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69  rameter] expansi
24e60 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74  on in the output
24e70 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63   of sqlite3_trac
24e80 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e()..**.** ^The 
24e90 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
24ea0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
24eb0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
24ec0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
24ed0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
24ee0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
24ef0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
24f00 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
24f10 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
24f20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
24f30 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
24f40 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
24f50 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
24f60 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
24f70 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
24f80 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
24f90 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
24fa0 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
24fb0 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
24fc0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
24fd0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
24fe0 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
24ff0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
25000 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
25010 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
25020 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
25030 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
25040 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
25050 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
25060 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
25070 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
25080 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
25090 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
250a0 61 63 6b 2e 20 20 49 6e 76 6f 6b 69 6e 67 0a 2a  ack.  Invoking.*
250b0 2a 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  * either [sqlite
250c0 33 5f 74 72 61 63 65 28 29 5d 20 6f 72 20 5b 73  3_trace()] or [s
250d0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
250e0 29 5d 20 77 69 6c 6c 20 63 61 6e 63 65 6c 20 74  )] will cancel t
250f0 68 65 0a 2a 2a 20 70 72 6f 66 69 6c 65 20 63 61  he.** profile ca
25100 6c 6c 62 61 63 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  llback..*/.SQLIT
25110 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
25120 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
25130 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
25140 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
25150 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
25160 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  void*);.SQLITE_D
25170 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a  EPRECATED void *
25180 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
25190 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
251a0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
251b0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
251c0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
251d0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
251e0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61  API3REF: SQL Tra
251f0 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a  ce Event Codes.*
25200 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
25210 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54  TE_TRACE.**.** T
25220 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69  hese constants i
25230 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20  dentify classes 
25240 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74 20 63  of events that c
25250 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a  an be monitored.
25260 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ** using the [sq
25270 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
25280 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e  ] tracing logic.
25290 20 20 54 68 65 20 4d 20 61 72 67 75 6d 65 6e 74    The M argument
252a0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
252b0 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50  trace_v2(D,M,X,P
252c0 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63  )] is an OR-ed c
252d0 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e  ombination of on
252e0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20  e or more of.** 
252f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
25300 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66  nstants.  ^The f
25310 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
25320 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
25330 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66  ack.** is one of
25340 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
25350 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
25360 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73  New tracing cons
25370 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64  tants may be add
25380 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
25390 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  eases..**.** ^A 
253a0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68  trace callback h
253b0 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  as four argument
253c0 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43  s: xCallback(T,C
253d0 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
253e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
253f0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   of the integer 
25400 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65  type codes above
25410 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75  ..** ^The C argu
25420 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f  ment is a copy o
25430 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f  f the context po
25440 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 20  inter passed in 
25450 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
25460 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
25470 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
25480 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  ]..** The P and 
25490 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
254a0 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
254b0 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
254c0 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  n T..**.** <dl>.
254d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
254e0 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c  E_STMT]] <dt>SQL
254f0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f  ITE_TRACE_STMT</
25500 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
25510 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
25520 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
25530 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65 70  oked when a prep
25540 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
25550 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 72  * first begins r
25560 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69  unning and possi
25570 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d  bly at other tim
25580 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  es during the.**
25590 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
255a0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
255b0 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74  ment, such as at
255c0 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65 61   the start of ea
255d0 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75  ch.** trigger su
255e0 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50  bprogram. ^The P
255f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
25600 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
25610 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25620 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72  ment]. ^The X ar
25630 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
25640 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
25650 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
25660 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74  unexpanded SQL t
25670 65 78 74 20 6f 66 20 74 68 65 20 70 72 65 70 61  ext of the prepa
25680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  red statement or
25690 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
256a0 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
256b0 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f  es the invocatio
256c0 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20  n of a trigger. 
256d0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63   ^The callback c
256e0 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68  an compute.** th
256f0 65 20 73 61 6d 65 20 74 65 78 74 20 74 68 61 74  e same text that
25700 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e   would have been
25710 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
25720 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
25730 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74  _trace()].** int
25740 65 72 66 61 63 65 20 62 79 20 75 73 69 6e 67 20  erface by using 
25750 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77  the X argument w
25760 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74  hen X begins wit
25770 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b  h "--" and invok
25780 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
25790 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d  expanded_sql(P)]
257a0 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
257b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
257c0 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53  _PROFILE]] <dt>S
257d0 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
257e0 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ILE</dt>.** <dd>
257f0 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
25800 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63  _PROFILE callbac
25810 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f  k provides appro
25820 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d  ximately the sam
25830 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
25840 20 61 73 20 69 73 20 70 72 6f 76 69 64 65 64 20   as is provided 
25850 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
25860 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62  profile()] callb
25870 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ack..** ^The P a
25880 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
25890 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65  nter to the [pre
258a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
258b0 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72   and the.** X ar
258c0 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
258d0 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65   a 64-bit intege
258e0 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20 65  r which is the e
258f0 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74  stimated of.** t
25900 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e  he number of nan
25910 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65  osecond that the
25920 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25930 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
25940 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
25950 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
25960 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
25970 64 20 77 68 65 6e 20 74 68 65 20 73 74 61 74 65  d when the state
25980 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a  ment finishes..*
25990 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
259a0 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51  ACE_ROW]] <dt>SQ
259b0 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f  LITE_TRACE_ROW</
259c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
259d0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
259e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
259f0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 70  ked whenever a p
25a00 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
25a10 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61  ment generates a
25a20 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72   single row of r
25a30 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65  esult.  .** ^The
25a40 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
25a50 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
25a60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25a70 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
25a80 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e  X argument is un
25a90 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  used..**.** [[SQ
25aa0 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
25ab0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
25ac0 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a  ACE_CLOSE</dt>.*
25ad0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
25ae0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c  _TRACE_CLOSE cal
25af0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
25b00 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
25b10 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  .** connection c
25b20 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50  loses..** ^The P
25b30 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
25b40 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
25b50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25b60 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  on] object.** an
25b70 64 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74  d the X argument
25b80 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c   is unused..** <
25b90 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
25ba0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
25bb0 54 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65  T       0x01.#de
25bc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
25bd0 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30  E_PROFILE    0x0
25be0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
25bf0 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20  _TRACE_ROW      
25c00 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53    0x04.#define S
25c10 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
25c20 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a  E      0x08../*.
25c30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
25c40 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d   Trace Hook.** M
25c50 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
25c60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
25c70 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58  3_trace_v2(D,M,X
25c80 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,P) interface re
25c90 67 69 73 74 65 72 73 20 61 20 74 72 61 63 65 20  gisters a trace 
25ca0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
25cb0 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b  tion X against [
25cc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25cd0 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72  ion] D, using pr
25ce0 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a  operty mask M.**
25cf0 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69   and context poi
25d00 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65  nter P.  ^If the
25d10 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a   X callback is.*
25d20 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65  * NULL or if the
25d30 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c   M mask is zero,
25d40 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73   then tracing is
25d50 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a   disabled.  The.
25d60 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68  ** M argument sh
25d70 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69 74 77  ould be the bitw
25d80 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e  ise OR-ed combin
25d90 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f  ation of.** zero
25da0 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45   or more [SQLITE
25db0 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74  _TRACE] constant
25dc0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63  s..**.** ^Each c
25dd0 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71  all to either sq
25de0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72  lite3_trace() or
25df0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
25e00 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a  2() overrides .*
25e10 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20  * (cancels) any 
25e20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73  prior calls to s
25e30 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
25e40 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
25e50 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  v2()..**.** ^The
25e60 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69   X callback is i
25e70 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
25e80 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74  any of the event
25e90 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
25ea0 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72  .** mask M occur
25eb0 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20  .  ^The integer 
25ec0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
25ed0 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  m the callback i
25ee0 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69  s currently.** i
25ef0 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74  gnored, though t
25f00 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69  his may change i
25f10 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
25f20 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s.  Callback.** 
25f30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
25f40 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65  should return ze
25f50 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74  ro to ensure fut
25f60 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ure compatibilit
25f70 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63  y..**.** ^A trac
25f80 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
25f90 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20  voked with four 
25fa0 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62  arguments: callb
25fb0 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
25fc0 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
25fd0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
25fe0 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a  SQLITE_TRACE].**
25ff0 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e   constants to in
26000 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20 63  dicate why the c
26010 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f  allback was invo
26020 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ked..** ^The C a
26030 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
26040 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
26050 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65   pointer..** The
26060 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
26070 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
26080 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
26090 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
260a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72  * The sqlite3_tr
260b0 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ace_v2() interfa
260c0 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  ce is intended t
260d0 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65  o replace the le
260e0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
260f0 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  es [sqlite3_trac
26100 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
26110 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f  3_profile()], bo
26120 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61  th of which.** a
26130 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a  re deprecated..*
26140 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  /.int sqlite3_tr
26150 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ace_v2(.  sqlite
26160 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75  3*,.  unsigned u
26170 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61  Mask,.  int(*xCa
26180 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64  llback)(unsigned
26190 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69  ,void*,void*,voi
261a0 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74  d*),.  void *pCt
261b0 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x.);../*.** CAPI
261c0 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
261d0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
261e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
261f0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
26200 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
26210 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
26220 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
26230 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
26240 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
26250 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
26260 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
26270 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
26280 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
26290 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
262a0 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
262b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
262c0 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
262d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
262e0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
262f0 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
26300 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
26310 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
26320 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
26330 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
26340 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
26350 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
26360 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
26370 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
26380 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
26390 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
263a0 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
263b0 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
263c0 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
263d0 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
263e0 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
263f0 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
26400 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
26410 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
26420 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
26430 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
26440 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
26450 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
26460 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
26470 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
26480 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
26490 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
264a0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
264b0 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
264c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
264d0 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
264e0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
264f0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
26500 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
26510 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
26520 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
26530 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
26540 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
26550 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
26560 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
26570 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
26580 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
26590 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
265a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
265b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
265c0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
265d0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
265e0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
265f0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
26600 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
26610 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
26620 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
26630 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
26640 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
26650 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
26660 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
26670 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
26680 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
26690 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
266a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
266b0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
266c0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
266d0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
266e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
266f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
26700 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
26710 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
26720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
26730 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
26740 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
26750 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
26760 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
26770 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
26780 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
26790 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
267a0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
267b0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
267c0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
267d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e  onnection.** CON
267e0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
267f0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  3.**.** ^These r
26800 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
26810 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
26820 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
26830 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
26840 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
26850 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
26860 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
26870 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
26880 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
26890 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
268a0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
268b0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
268c0 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
268d0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
268e0 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
268f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26900 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
26910 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
26920 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
26930 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
26940 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
26950 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
26960 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
26970 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
26980 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
26990 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
269a0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
269b0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
269c0 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
269d0 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
269e0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
269f0 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
26a00 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
26a10 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
26a20 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
26a30 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
26a40 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
26a50 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
26a60 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
26a70 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
26a80 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
26a90 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
26aa0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
26ab0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
26ac0 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
26ad0 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
26ae0 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
26af0 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
26b00 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
26b10 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
26b20 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
26b30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
26b40 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
26b50 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
26b60 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ing will be UTF-
26b70 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20  8 for databases 
26b80 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
26b90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
26ba0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
26bb0 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61  v2().  ^The defa
26bc0 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
26bd0 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72   databases.** cr
26be0 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69  eated using sqli
26bf0 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c  te3_open16() wil
26c00 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74  l be UTF-16 in t
26c10 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
26c20 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  rder..**.** Whet
26c30 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
26c40 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
26c50 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
26c60 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
26c70 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
26c80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26c90 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
26ca0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
26cb0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
26cc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
26cd0 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
26ce0 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
26cf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
26d00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26d10 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
26d20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
26d30 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
26d40 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
26d50 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
26d60 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
26d70 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
26d80 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
26d90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26da0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
26db0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
26dc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26dd0 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
26de0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
26df0 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
26e00 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
26e10 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
26e20 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
26e30 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
26e40 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
26e50 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
26e60 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
26e70 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
26e80 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
26e90 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
26ea0 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
26eb0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
26ec0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
26ed0 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
26ee0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
26ef0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
26f00 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
26f10 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
26f20 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
26f30 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
26f40 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
26f50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
26f60 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
26f70 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
26f80 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
26f90 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
26fa0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
26fb0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
26fc0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
26fd0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
26fe0 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
26ff0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
27000 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
27010 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
27020 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
27030 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
27040 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
27050 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
27060 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
27070 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
27080 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
27090 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
270a0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
270b0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
270c0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
270d0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
270e0 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
270f0 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
27100 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
27110 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
27120 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
27130 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
27140 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
27150 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
27160 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
27170 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
27180 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
27190 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
271a0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
271b0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
271c0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
271d0 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
271e0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
271f0 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
27200 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
27210 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
27220 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
27230 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
27240 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
27250 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
27260 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
27270 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
27280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27290 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
272a0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
272b0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
272c0 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
272d0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
272e0 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
272f0 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
27300 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
27310 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
27320 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
27330 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
27340 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
27350 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27360 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
27370 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
27380 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
27390 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
273a0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
273b0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
273c0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
273d0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
273e0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
273f0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
27400 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
27410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
27420 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
27430 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
27440 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
27450 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
27460 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
27470 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
27480 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
27490 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
274a0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
274b0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
274c0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
274d0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
274e0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
274f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
27500 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
27510 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
27520 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
27530 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
27540 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
27550 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
27560 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
27570 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
27580 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
27590 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
275a0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
275b0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
275c0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
275d0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
275e0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
275f0 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
27600 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27610 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
27620 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
27630 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
27640 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
27650 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
27660 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
27670 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
27680 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
27690 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
276a0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
276b0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
276c0 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
276d0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
276e0 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
276f0 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
27700 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
27710 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
27720 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
27730 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
27740 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
27750 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
27760 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
27770 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
27780 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
27790 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
277a0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
277b0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
277c0 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
277d0 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
277e0 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
277f0 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
27800 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
27810 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
27820 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
27830 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
27840 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
27850 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
27860 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
27870 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
27880 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
27890 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
278a0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
278b0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
278c0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
278d0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
278e0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
278f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27900 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
27910 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
27920 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
27930 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
27940 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
27950 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
27960 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
27970 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
27980 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
27990 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
279a0 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
279b0 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
279c0 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
279d0 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
279e0 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
279f0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
27a00 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
27a10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
27a20 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
27a30 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 61  t in the third a
27a40 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
27a50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
27a60 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
27a70 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
27a80 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
27a90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
27aa0 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
27ab0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
27ac0 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
27ad0 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
27ae0 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
27af0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
27b00 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  * URI filename i
27b10 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
27b20 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
27b30 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
27b40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
27b50 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
27b60 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
27b70 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
27b80 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
27b90 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
27ba0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
27bb0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
27bc0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
27bd0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
27be0 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
27bf0 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
27c00 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
27c10 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
27c20 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
27c30 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
27c40 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
27c50 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
27c60 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
27c70 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
27c80 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
27c90 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
27ca0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
27cb0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
27cc0 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
27cd0 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
27ce0 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
27cf0 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
27d00 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
27d10 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
27d20 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
27d30 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
27d40 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
27d50 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
27d60 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
27d70 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
27d80 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
27d90 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
27da0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
27db0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
27dc0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
27dd0 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
27de0 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
27df0 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
27e00 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
27e10 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
27e20 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
27e30 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
27e40 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
27e50 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
27e60 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
27e70 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
27e80 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
27e90 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
27ea0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
27eb0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
27ec0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
27ed0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
27ee0 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
27ef0 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
27f00 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
27f10 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
27f20 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
27f30 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
27f40 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
27f50 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
27f60 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
27f70 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
27f80 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
27f90 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
27fa0 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
27fb0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
27fc0 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
27fd0 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
27fe0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
27ff0 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
28000 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
28010 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
28020 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
28030 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
28040 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
28050 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
28060 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
28070 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
28080 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
28090 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
280a0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
280b0 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
280c0 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
280d0 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
280e0 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
280f0 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
28100 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
28110 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
28120 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
28130 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
28140 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
28150 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
28160 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
28170 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
28180 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
28190 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
281a0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
281b0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
281c0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
281d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
281e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
281f0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
28200 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
28210 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
28220 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
28230 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
28240 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
28250 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
28260 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
28270 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
28280 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
28290 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
282a0 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
282b0 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
282c0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
282d0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
282e0 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
282f0 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
28300 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
28310 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
28320 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
28330 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
28340 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
28350 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
28360 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
28370 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
28380 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
28390 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
283a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
283b0 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
283c0 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
283d0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
283e0 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
283f0 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
28400 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
28410 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
28420 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
28430 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
28440 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
28450 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
28460 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
28470 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
28480 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
28490 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
284a0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
284b0 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
284c0 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
284d0 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
284e0 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
284f0 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
28500 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
28510 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
28520 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
28530 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
28540 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
28550 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
28560 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
28570 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
28580 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
28590 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
285a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
285b0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
285c0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
285d0 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
285e0 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
285f0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
28600 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
28610 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
28620 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
28630 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
28640 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
28650 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
28660 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
28670 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
28680 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
28690 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
286a0 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
286b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
286c0 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
286d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
286e0 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
286f0 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
28700 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
28710 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
28720 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
28730 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
28740 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
28750 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
28760 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
28770 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
28780 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
28790 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
287a0 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
287b0 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
287c0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
287d0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
287e0 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
287f0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
28800 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
28810 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
28820 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
28830 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
28840 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
28850 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
28860 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
28870 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
28880 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
28890 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
288a0 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
288b0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
288c0 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
288d0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
288e0 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
288f0 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
28900 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
28910 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
28920 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
28930 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
28940 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
28950 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
28960 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
28970 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
28980 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
28990 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
289a0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
289b0 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
289c0 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
289d0 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
289e0 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
289f0 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
28a00 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
28a10 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
28a20 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
28a30 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
28a40 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
28a50 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
28a60 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
28a70 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
28a80 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
28a90 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
28aa0 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
28ab0 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
28ac0 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
28ad0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
28ae0 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
28af0 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
28b00 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
28b10 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
28b20 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
28b30 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
28b40 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
28b50 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
28b60 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
28b70 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
28b80 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
28b90 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
28ba0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
28bb0 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
28bc0 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
28bd0 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
28be0 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
28bf0 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
28c00 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
28c10 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
28c20 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
28c30 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
28c40 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
28c50 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
28c60 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
28c70 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
28c80 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
28c90 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
28ca0 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
28cb0 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
28cc0 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
28cd0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
28ce0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
28cf0 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
28d00 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
28d10 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
28d20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
28d30 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
28d40 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
28d50 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
28d60 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
28d70 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
28d80 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
28d90 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
28da0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
28db0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
28dc0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
28dd0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
28de0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
28df0 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
28e00 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
28e10 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
28e20 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
28e30 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
28e40 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
28e50 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
28e60 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
28e70 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
28e80 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
28e90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
28ea0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
28eb0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
28ec0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
28ed0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
28ee0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
28ef0 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
28f00 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
28f10 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
28f20 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
28f30 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
28f40 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
28f50 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
28f60 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
28f70 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
28f80 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
28f90 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
28fa0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
28fb0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
28fc0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
28fd0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
28fe0 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
28ff0 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
29000 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
29010 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
29020 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
29030 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
29040 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
29050 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
29060 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
29070 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
29080 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
29090 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
290a0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
290b0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
290c0 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
290d0 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
290e0 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
290f0 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
29100 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
29110 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
29120 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
29130 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
29140 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
29150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
29160 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
29170 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
29180 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
29190 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
291a0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
291b0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
291c0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
291d0 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
291e0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
291f0 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
29200 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
29210 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
29220 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
29230 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
29240 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
29250 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
29260 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
29270 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
29280 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
29290 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
292a0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
292b0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
292c0 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
292d0 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
292e0 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
292f0 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
29300 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
29310 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
29320 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
29330 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
29340 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
29350 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
29360 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
29370 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
29380 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
29390 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
293a0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
293b0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
293c0 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
293d0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
293e0 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
293f0 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
29400 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
29410 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
29420 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
29430 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
29440 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
29450 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
29460 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
29470 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
29480 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
29490 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
294a0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
294b0 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
294c0 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
294d0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
294e0 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
294f0 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
29500 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
29510 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
29520 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
29530 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
29540 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
29550 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
29560 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
29570 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
29580 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
29590 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
295a0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
295b0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
295c0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
295d0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
295e0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
295f0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
29600 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
29610 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
29620 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
29630 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
29640 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
29650 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
29660 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
29670 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
29680 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
29690 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
296a0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
296b0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
296c0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
296d0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
296e0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
296f0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
29700 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
29710 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
29720 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
29730 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
29740 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
29750 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
29760 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
29770 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
29780 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
29790 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
297a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
297b0 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
297c0 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
297d0 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
297e0 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
297f0 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
29800 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
29810 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
29820 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
29830 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
29840 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
29850 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
29860 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
29870 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
29880 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
29890 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
298a0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
298b0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
298c0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
298d0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
298e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
298f0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
29900 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
29910 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
29920 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
29930 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
29940 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
29950 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
29960 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
29970 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
29980 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
29990 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
299a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
299b0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
299c0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
299d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
299e0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
299f0 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
29a00 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
29a10 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
29a20 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
29a30 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
29a40 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
29a50 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
29a60 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
29a70 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
29a80 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
29a90 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
29aa0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
29ab0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
29ac0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
29ad0 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
29ae0 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
29af0 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
29b00 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
29b10 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
29b20 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
29b30 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
29b40 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
29b50 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
29b60 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
29b70 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
29b80 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
29b90 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
29ba0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
29bb0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
29bc0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
29bd0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
29be0 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
29bf0 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
29c00 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
29c10 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
29c20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
29c30 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
29c40 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
29c50 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
29c60 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
29c70 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
29c80 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
29c90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
29ca0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
29cb0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
29cc0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
29cd0 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
29ce0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
29cf0 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
29d00 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
29d10 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
29d20 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
29d30 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
29d40 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
29d50 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
29d60 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
29d70 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
29d80 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
29d90 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
29da0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
29db0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
29dc0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
29dd0 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
29de0 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
29df0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
29e00 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
29e10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
29e20 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
29e30 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
29e40 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
29e50 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
29e60 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
29e70 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
29e80 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
29e90 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
29ea0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
29eb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
29ec0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
29ed0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
29ee0 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
29ef0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
29f00 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
29f10 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
29f20 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
29f30 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
29f40 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
29f50 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
29f60 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
29f70 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
29f80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
29f90 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
29fa0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
29fb0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
29fc0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
29fd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
29fe0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
29ff0 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
2a000 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2a010 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
2a020 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
2a030 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
2a040 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
2a050 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2a060 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
2a070 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
2a080 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
2a090 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
2a0a0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
2a0b0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
2a0c0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
2a0d0 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
2a0e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
2a0f0 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
2a100 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
2a110 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
2a120 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
2a130 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
2a140 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
2a150 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
2a160 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
2a170 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
2a180 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
2a190 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
2a1a0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
2a1b0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
2a1c0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
2a1d0 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
2a1e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2a1f0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
2a200 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2a210 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
2a220 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
2a230 20 53 65 65 20 74 68 65 20 5b 55 52 49 20 66 69   See the [URI fi
2a240 6c 65 6e 61 6d 65 5d 20 64 6f 63 75 6d 65 6e 74  lename] document
2a250 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2a260 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2a270 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2a280 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
2a290 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
2a2a0 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
2a2b0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
2a2c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  );.int sqlite3_u
2a2d0 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
2a2e0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
2a2f0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
2a300 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
2a310 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2a320 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
2a330 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
2a340 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
2a350 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
2a360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
2a370 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
2a380 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  sages.** METHOD:
2a390 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
2a3a0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2a3b0 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  nt sqlite3_* API
2a3c0 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
2a3d0 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62   with .** [datab
2a3e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2a3f0 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74  D failed, then t
2a400 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
2a410 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a  de(D) interface.
2a420 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ** returns the n
2a430 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
2a440 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
2a450 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
2a460 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63  or that.** API c
2a470 61 6c 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  all..** ^The sql
2a480 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
2a490 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
2a4a0 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
2a4b0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
2a4c0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
2a4d0 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
2a4e0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
2a4f0 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
2a500 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
2a510 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
2a520 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20  *.** The values 
2a530 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2a540 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 61 6e  te3_errcode() an
2a550 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
2a560 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
2a570 28 29 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  () might change 
2a580 77 69 74 68 20 65 61 63 68 20 41 50 49 20 63 61  with each API ca
2a590 6c 6c 2e 0a 2a 2a 20 45 78 63 65 70 74 2c 20 74  ll..** Except, t
2a5a0 68 65 72 65 20 61 72 65 20 73 6f 6d 65 20 69 6e  here are some in
2a5b0 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72  terfaces that ar
2a5c0 65 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  e guaranteed to 
2a5d0 6e 65 76 65 72 0a 2a 2a 20 63 68 61 6e 67 65 20  never.** change 
2a5e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2a5f0 20 65 72 72 6f 72 20 63 6f 64 65 2e 20 20 54 68   error code.  Th
2a600 65 20 65 72 72 6f 72 2d 63 6f 64 65 20 70 72 65  e error-code pre
2a610 73 65 72 76 69 6e 67 0a 2a 2a 20 69 6e 74 65 72  serving.** inter
2a620 66 61 63 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a  faces are:.**.**
2a630 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71   <ul>.** <li> sq
2a640 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a  lite3_errcode().
2a650 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f  ** <li> sqlite3_
2a660 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
2a670 28 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74  ().** <li> sqlit
2a680 65 33 5f 65 72 72 6d 73 67 28 29 0a 2a 2a 20 3c  e3_errmsg().** <
2a690 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  li> sqlite3_errm
2a6a0 73 67 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a  sg16().** </ul>.
2a6b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a6c0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
2a6d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
2a6e0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
2a6f0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
2a700 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
2a710 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
2a720 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
2a730 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
2a740 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
2a750 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
2a760 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
2a770 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
2a780 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
2a790 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
2a7a0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
2a7b0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
2a7c0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
2a7d0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
2a7e0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
2a7f0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
2a800 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
2a810 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
2a820 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
2a830 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
2a840 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
2a850 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2a860 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
2a870 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
2a880 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
2a890 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
2a8a0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
2a8b0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
2a8c0 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
2a8d0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
2a8e0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
2a8f0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
2a900 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
2a910 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
2a920 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2a930 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
2a940 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
2a950 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
2a960 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
2a970 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
2a980 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
2a990 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
2a9a0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
2a9b0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
2a9c0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
2a9d0 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
2a9e0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
2a9f0 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
2aa00 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
2aa10 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
2aa20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
2aa30 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
2aa40 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
2aa50 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
2aa60 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
2aa70 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
2aa80 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
2aa90 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
2aaa0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
2aab0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
2aac0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
2aad0 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
2aae0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
2aaf0 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
2ab00 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
2ab10 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
2ab20 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
2ab30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
2ab40 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
2ab50 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
2ab60 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
2ab70 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
2ab80 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
2ab90 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
2aba0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
2abb0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
2abc0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
2abd0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
2abe0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
2abf0 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
2ac00 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
2ac10 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
2ac20 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
2ac30 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
2ac40 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
2ac50 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
2ac60 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
2ac70 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
2ac80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
2ac90 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
2aca0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
2acb0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2acc0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
2acd0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2ace0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
2acf0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
2ad00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
2ad10 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
2ad20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
2ad30 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2ad40 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
2ad50 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
2ad60 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
2ad70 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
2ad80 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
2ad90 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
2ada0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
2adb0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
2adc0 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65  t that.** has be
2add0 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  en compiled into
2ade0 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64   binary form and
2adf0 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20   is ready to be 
2ae00 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  evaluated..**.**
2ae10 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53   Think of each S
2ae20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
2ae30 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75  a separate compu
2ae40 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68  ter program.  Th
2ae50 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
2ae60 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65  L text is source
2ae70 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72   code.  A prepar
2ae80 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
2ae90 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63  ect .** is the c
2aea0 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63  ompiled object c
2aeb0 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75  ode.  All SQL mu
2aec0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
2aed0 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72  into a.** prepar
2aee0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66  ed statement bef
2aef0 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75  ore it can be ru
2af00 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  n..**.** The lif
2af10 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65  e-cycle of a pre
2af20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2af30 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67  object usually g
2af40 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  oes like this:.*
2af50 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2af60 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65  > Create the pre
2af70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2af80 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
2af90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2afa0 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ()]..** <li> Bin
2afb0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72  d values to [par
2afc0 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
2afd0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2afe0 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
2aff0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
2b000 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
2b010 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2b020 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
2b030 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
2b040 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65  i> Reset the pre
2b050 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b060 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2b070 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
2b080 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
2b090 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
2b0a0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
2b0b0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
2b0c0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
2b0d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2b0e0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
2b0f0 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  /ol>.*/.typedef 
2b100 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
2b110 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
2b120 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b130 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
2b140 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ts.** METHOD: sq
2b150 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lite3.**.** ^(Th
2b160 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
2b170 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
2b180 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
2b190 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
2b1a0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
2b1b0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
2b1c0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
2b1d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2b1e0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
2b1f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
2b200 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
2b210 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
2b220 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
2b230 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
2b240 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
2b250 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
2b260 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
2b270 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
2b280 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
2b290 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
2b2a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2b2b0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
2b2c0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
2b2d0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
2b2e0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
2b2f0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
2b300 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
2b310 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
2b320 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
2b330 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
2b340 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
2b350 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
2b360 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
2b370 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
2b380 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
2b390 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
2b3a0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
2b3b0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
2b3c0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
2b3d0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
2b3e0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
2b3f0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
2b400 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
2b410 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
2b420 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
2b430 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
2b440 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
2b450 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
2b460 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
2b470 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
2b480 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
2b490 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
2b4a0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
2b4b0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
2b4c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
2b4d0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
2b4e0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
2b4f0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
2b500 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
2b510 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
2b520 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
2b530 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
2b540 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
2b550 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
2b560 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
2b570 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2b580 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
2b590 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
2b5a0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
2b5b0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
2b5c0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
2b5d0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
2b5e0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
2b5f0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
2b600 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
2b610 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
2b620 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
2b630 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
2b640 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
2b650 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
2b660 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
2b670 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
2b680 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
2b690 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
2b6a0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
2b6b0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
2b6c0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
2b6d0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
2b6e0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
2b6f0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
2b700 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
2b710 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
2b720 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
2b730 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
2b740 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
2b750 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
2b760 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
2b770 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
2b780 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
2b790 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
2b7a0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
2b7b0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
2b7c0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
2b7d0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
2b7e0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
2b7f0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
2b800 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
2b810 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
2b820 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
2b830 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
2b840 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2b850 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
2b860 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
2b870 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
2b880 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
2b890 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
2b8a0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
2b8b0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
2b8c0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
2b8d0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
2b8e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
2b8f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
2b900 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
2b910 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
2b920 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
2b930 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
2b940 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
2b950 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
2b960 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
2b970 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
2b980 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2b990 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
2b9a0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
2b9b0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
2b9c0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
2b9d0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
2b9e0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
2b9f0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
2ba00 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
2ba10 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
2ba20 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
2ba30 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
2ba40 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2ba50 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
2ba60 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
2ba70 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
2ba80 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
2ba90 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
2baa0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
2bab0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2bac0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2bad0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
2bae0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
2baf0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
2bb00 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
2bb10 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2bb20 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2bb30 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2bb40 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2bb50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2bb60 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
2bb70 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
2bb80 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
2bb90 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2bba0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
2bbb0 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
2bbc0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
2bbd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2bbe0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2bbf0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
2bc00 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
2bc10 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
2bc20 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2bc30 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
2bc40 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
2bc50 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
2bc60 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
2bc70 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
2bc80 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
2bc90 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2bca0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2bcb0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2bcc0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2bcd0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2bce0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
2bcf0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
2bd00 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
2bd10 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
2bd20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2bd30 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2bd40 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
2bd50 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
2bd60 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
2bd70 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2bd80 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
2bd90 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
2bda0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
2bdb0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2bdc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2bdd0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
2bde0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
2bdf0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2be00 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2be10 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
2be20 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
2be30 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
2be40 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2be50 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2be60 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  t.  If [sqlite3_
2be70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2be80 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65  .** the equivale
2be90 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f  nt tries to allo
2bea0 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d  cate space for m
2beb0 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61  ore than this ma
2bec0 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e  ny opcodes.** in
2bed0 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72   a single prepar
2bee0 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e  ed statement, an
2bef0 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72   SQLITE_NOMEM er
2bf00 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
2bf10 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2bf20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2bf30 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
2bf40 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
2bf50 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
2bf60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2bf70 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
2bf80 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
2bf90 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
2bfa0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2bfb0 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
2bfc0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2bfd0 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
2bfe0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2bff0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
2c000 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
2c010 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
2c020 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
2c030 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
2c040 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
2c050 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2c060 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2c070 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
2c080 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
2c090 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
2c0a0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
2c0b0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
2c0c0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
2c0d0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
2c0e0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2c0f0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2c100 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
2c110 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2c120 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
2c130 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2c140 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
2c150 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
2c160 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
2c170 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
2c180 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
2c190 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
2c1a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
2c1b0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
2c1c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2c1d0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
2c1e0 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
2c1f0 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
2c200 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2c210 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2c220 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2c230 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
2c240 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
2c250 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2c260 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
2c270 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
2c280 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
2c290 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c2a0 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
2c2b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
2c2c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2c2d0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
2c2e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c2f0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
2c300 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2c310 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
2c320 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2c330 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2c340 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
2c350 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2c360 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
2c370 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
2c380 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2c390 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
2c3a0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
2c3b0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
2c3c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
2c3d0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
2c3e0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
2c3f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
2c400 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
2c410 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
2c420 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2c430 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
2c440 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
2c450 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2c460 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2c470 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
2c480 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2c490 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2c4a0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
2c4b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2c4c0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
2c4d0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
2c4e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2c4f0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2c500 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
2c510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c520 20 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a   Prepare Flags.*
2c530 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2c540 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
2c550 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63  ous flags that c
2c560 61 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74  an be passed int
2c570 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22  o.** "prepFlags"
2c580 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2c590 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2c5a0 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20  re_v3()] and.** 
2c5b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c5c0 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61  16_v3()] interfa
2c5d0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66  ces..**.** New f
2c5e0 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 65  lags may be adde
2c5f0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
2c600 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
2c610 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
2c620 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2c630 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64  ERSISTENT]] ^(<d
2c640 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  t>SQLITE_PREPARE
2c650 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e  _PERSISTENT</dt>
2c660 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49  .** <dd>The SQLI
2c670 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2c680 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20  STENT flag is a 
2c690 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72  hint to the quer
2c6a0 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61  y planner.** tha
2c6b0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2c6c0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2c6d0 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20   retained for a 
2c6e0 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a  long time and.**
2c6f0 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64   probably reused
2c700 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e   many times.)^ ^
2c710 57 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61  Without this fla
2c720 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  g, [sqlite3_prep
2c730 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64  are_v3()].** and
2c740 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c750 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65  e16_v3()] assume
2c760 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
2c770 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ed statement wil
2c780 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75  l .** be used ju
2c790 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f  st once or at mo
2c7a0 73 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61  st a few times a
2c7b0 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65  nd then destroye
2c7c0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2c7d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c7e0 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e  relatively soon.
2c7f0 20 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   The current imp
2c800 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73  lementation acts
2c810 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  .** on this hint
2c820 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65   by avoiding the
2c830 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69   use of [lookasi
2c840 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73  de memory] so as
2c850 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65   not to.** deple
2c860 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73  te the limited s
2c870 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  tore of lookasid
2c880 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65  e memory. Future
2c890 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20   versions of.** 
2c8a0 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f  SQLite may act o
2c8b0 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 66  n this hint diff
2c8c0 65 72 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5b  erently..**.** [
2c8d0 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  [SQLITE_PREPARE_
2c8e0 4e 4f 52 4d 41 4c 49 5a 45 5d 5d 20 3c 64 74 3e  NORMALIZE]] <dt>
2c8f0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2c900 4f 52 4d 41 4c 49 5a 45 3c 2f 64 74 3e 0a 2a 2a  ORMALIZE</dt>.**
2c910 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f   <dd>The SQLITE_
2c920 50 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a  PREPARE_NORMALIZ
2c930 45 20 66 6c 61 67 20 69 73 20 61 20 6e 6f 2d 6f  E flag is a no-o
2c940 70 2e 20 54 68 69 73 20 66 6c 61 67 20 75 73 65  p. This flag use
2c950 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65 71 75 69  d.** to be requi
2c960 72 65 64 20 66 6f 72 20 61 6e 79 20 70 72 65 70  red for any prep
2c970 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74  ared statement t
2c980 68 61 74 20 77 61 6e 74 65 64 20 74 6f 20 75 73  hat wanted to us
2c990 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
2c9a0 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c  3_normalized_sql
2c9b0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
2c9c0 48 6f 77 65 76 65 72 2c 20 74 68 65 0a 2a 2a 20  However, the.** 
2c9d0 5b 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69  [sqlite3_normali
2c9e0 7a 65 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72  zed_sql()] inter
2c9f0 66 61 63 65 20 69 73 20 6e 6f 77 20 61 76 61 69  face is now avai
2ca00 6c 61 62 6c 65 20 74 6f 20 61 6c 6c 0a 2a 2a 20  lable to all.** 
2ca10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ca20 6e 74 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20  nts, regardless 
2ca30 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
2ca40 74 20 74 68 65 79 20 75 73 65 20 74 68 69 73 0a  t they use this.
2ca50 2a 2a 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 5b  ** flag..**.** [
2ca60 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  [SQLITE_PREPARE_
2ca70 4e 4f 5f 56 54 41 42 5d 5d 20 3c 64 74 3e 53 51  NO_VTAB]] <dt>SQ
2ca80 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f  LITE_PREPARE_NO_
2ca90 56 54 41 42 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  VTAB</dt>.** <dd
2caa0 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50  >The SQLITE_PREP
2cab0 41 52 45 5f 4e 4f 5f 56 54 41 42 20 66 6c 61 67  ARE_NO_VTAB flag
2cac0 20 63 61 75 73 65 73 20 74 68 65 20 53 51 4c 20   causes the SQL 
2cad0 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 72  compiler.** to r
2cae0 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 28  eturn an error (
2caf0 65 72 72 6f 72 20 63 6f 64 65 20 53 51 4c 49 54  error code SQLIT
2cb00 45 5f 45 52 52 4f 52 29 20 69 66 20 74 68 65 20  E_ERROR) if the 
2cb10 73 74 61 74 65 6d 65 6e 74 20 75 73 65 73 0a 2a  statement uses.*
2cb20 2a 20 61 6e 79 20 76 69 72 74 75 61 6c 20 74 61  * any virtual ta
2cb30 62 6c 65 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  bles..** </dl>.*
2cb40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2cb50 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2cb60 45 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ENT             
2cb70 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51   0x01.#define SQ
2cb80 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52  LITE_PREPARE_NOR
2cb90 4d 41 4c 49 5a 45 20 20 20 20 20 20 20 20 20 20  MALIZE          
2cba0 20 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e       0x02.#defin
2cbb0 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2cbc0 5f 4e 4f 5f 56 54 41 42 20 20 20 20 20 20 20 20  _NO_VTAB        
2cbd0 20 20 20 20 20 20 20 20 20 30 78 30 34 0a 0a 2f           0x04../
2cbe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2cbf0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
2cc00 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
2cc10 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
2cc20 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
2cc30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2cc40 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  e3.** CONSTRUCTO
2cc50 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
2cc60 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
2cc70 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2cc80 74 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  t, it must first
2cc90 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
2cca0 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
2ccb0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
2ccc0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
2ccd0 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74  ines.  Or, in ot
2cce0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65  her words, these
2ccf0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
2cd00 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f   constructors fo
2cd10 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2cd20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
2cd30 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  t..**.** The pre
2cd40 66 65 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74  ferred routine t
2cd50 6f 20 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65  o use is [sqlite
2cd60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
2cd70 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
2cd80 33 5f 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74  3_prepare()] int
2cd90 65 72 66 61 63 65 20 69 73 20 6c 65 67 61 63 79  erface is legacy
2cda0 20 61 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61   and should be a
2cdb0 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69  voided..** [sqli
2cdc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2cdd0 5d 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 22  ] has an extra "
2cde0 70 72 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f  prepFlags" optio
2cdf0 6e 20 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a  n that is used.*
2ce00 2a 20 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75  * for special pu
2ce10 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  rposes..**.** Th
2ce20 65 20 75 73 65 20 6f 66 20 74 68 65 20 55 54 46  e use of the UTF
2ce30 2d 38 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  -8 interfaces is
2ce40 20 70 72 65 66 65 72 72 65 64 2c 20 61 73 20 53   preferred, as S
2ce50 51 4c 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a  QLite currently.
2ce60 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73  ** does all pars
2ce70 69 6e 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e  ing using UTF-8.
2ce80 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74    The UTF-16 int
2ce90 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
2cea0 69 64 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e  ided.** as a con
2ceb0 76 65 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55  venience.  The U
2cec0 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73  TF-16 interfaces
2ced0 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74   work by convert
2cee0 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  ing the.** input
2cef0 20 74 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38   text into UTF-8
2cf00 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20  , then invoking 
2cf10 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2cf20 67 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63  g UTF-8 interfac
2cf30 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
2cf40 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
2cf50 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
2cf60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
2cf70 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
2cf80 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
2cf90 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2cfa0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2cfb0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2cfc0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
2cfd0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
2cfe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cff0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
2d000 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
2d010 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
2d020 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
2d030 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
2d040 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2d050 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
2d060 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
2d070 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
2d080 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20  ite3_prepare(), 
2d090 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d0a0 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c  v2(),.** and sql
2d0b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2d0c0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
2d0d0 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
2d0e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d0f0 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  (), sqlite3_prep
2d100 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61  are16_v2(),.** a
2d110 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2d120 72 65 31 36 5f 76 33 28 29 20 75 73 65 20 55 54  re16_v3() use UT
2d130 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
2d140 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
2d150 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  nt is negative, 
2d160 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
2d170 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
2d180 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
2d190 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
2d1a0 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65  is positive, the
2d1b0 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e  n it is the.** n
2d1c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72  umber of bytes r
2d1d0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
2d1e0 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72  ^If nByte is zer
2d1f0 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61  o, then no prepa
2d200 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2d210 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a   is generated..*
2d220 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  * If the caller 
2d230 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73  knows that the s
2d240 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
2d250 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
2d260 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20  , then.** there 
2d270 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f  is a small perfo
2d280 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
2d290 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   to passing an n
2d2a0 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
2d2b0 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  hat.** is the nu
2d2c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2d2d0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
2d2e0 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
2d2f0 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
2d300 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
2d310 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
2d320 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
2d330 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
2d340 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
2d350 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
2d360 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
2d370 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
2d380 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
2d390 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
2d3a0 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
2d3b0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
2d3c0 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
2d3d0 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
2d3e0 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
2d3f0 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
2d400 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
2d410 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
2d420 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
2d430 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d440 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
2d450 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
2d460 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
2d470 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
2d480 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
2d490 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
2d4a0 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
2d4b0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
2d4c0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
2d4d0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
2d4e0 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
2d4f0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
2d500 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
2d510 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
2d520 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
2d530 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
2d540 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
2d550 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
2d560 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
2d570 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2d580 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
2d590 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
2d5a0 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
2d5b0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
2d5c0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
2d5d0 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
2d5e0 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
2d5f0 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
2d600 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2d610 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
2d620 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2d630 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2d640 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2d650 70 72 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71  prepare_v2(), sq
2d660 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2d670 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  (), sqlite3_prep
2d680 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61  are16_v2(),.** a
2d690 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2d6a0 72 65 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66  re16_v3() interf
2d6b0 61 63 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65  aces are recomme
2d6c0 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
2d6d0 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68   programs..** Th
2d6e0 65 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  e older interfac
2d6f0 65 73 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70  es (sqlite3_prep
2d700 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
2d710 33 5f 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a  3_prepare16()).*
2d720 2a 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  * are retained f
2d730 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
2d740 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
2d750 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
2d760 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
2d770 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66   the "vX" interf
2d780 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
2d790 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2d7a0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
2d7b0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2d7c0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
2d7d0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
2d7e0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
2d7f0 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
2d800 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
2d810 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
2d820 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
2d830 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
2d840 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
2d850 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
2d860 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
2d870 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
2d880 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
2d890 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2d8a0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
2d8b0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
2d8c0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
2d8d0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
2d8e0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
2d8f0 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
2d900 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
2d910 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
2d920 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
2d930 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
2d940 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
2d950 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
2d960 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
2d970 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
2d980 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
2d990 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2d9a0 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
2d9b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
2d9c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2d9d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
2d9e0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
2d9f0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
2da00 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
2da10 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
2da20 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2da30 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
2da40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2da50 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
2da60 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
2da70 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
2da80 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
2da90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
2daa0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
2dab0 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
2dac0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2dad0 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
2dae0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
2daf0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
2db00 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
2db10 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
2db20 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
2db30 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2db40 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
2db50 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
2db60 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
2db70 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2db80 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
2db90 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
2dba0 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
2dbb0 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
2dbc0 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
2dbd0 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
2dbe0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
2dbf0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2dc00 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
2dc10 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
2dc20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
2dc30 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2dc40 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
2dc50 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
2dc60 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
2dc70 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
2dc80 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
2dc90 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
2dca0 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
2dcb0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2dcc0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
2dcd0 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
2dce0 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
2dcf0 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
2dd00 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
2dd10 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
2dd20 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2dd30 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
2dd40 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
2dd50 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2dd60 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
2dd70 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
2dd80 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
2dd90 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
2dda0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
2ddb0 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
2ddc0 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
2ddd0 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
2dde0 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
2ddf0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2de00 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
2de10 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
2de20 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33  *.** <p>^sqlite3
2de30 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 64 69  _prepare_v3() di
2de40 66 66 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74  ffers from sqlit
2de50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
2de60 6f 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a  only in having.*
2de70 2a 20 74 68 65 20 65 78 74 72 61 20 70 72 65 70  * the extra prep
2de80 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c  Flags parameter,
2de90 20 77 68 69 63 68 20 69 73 20 61 20 62 69 74 20   which is a bit 
2dea0 61 72 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67  array consisting
2deb0 20 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d   of zero or.** m
2dec0 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
2ded0 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2dee0 53 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45  STENT|SQLITE_PRE
2def0 50 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20  PARE_*] flags.  
2df00 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
2df10 70 72 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74  prepare_v2() int
2df20 65 72 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61  erface works exa
2df30 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
2df40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
2df50 61 72 65 5f 76 33 28 29 20 77 69 74 68 20 61 20  are_v3() with a 
2df60 7a 65 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70  zero prepFlags p
2df70 61 72 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74  arameter..*/.int
2df80 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2df90 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2dfa0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2dfb0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2dfc0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2dfd0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2dfe0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2dff0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2e000 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2e010 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2e020 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2e030 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2e040 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2e050 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2e060 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2e070 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2e080 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2e090 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2e0a0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2e0b0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2e0c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2e0d0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
2e0e0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2e0f0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2e100 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2e110 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2e120 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2e130 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2e140 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2e150 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2e160 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2e170 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2e180 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2e190 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2e1a0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2e1b0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2e1c0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2e1d0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2e1e0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2e1f0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2e200 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2e210 33 5f 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20  3_prepare_v3(.  
2e220 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2e230 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2e240 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2e250 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2e260 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2e270 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2e280 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2e290 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2e2a0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2e2b0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2e2c0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e  n bytes. */.  un
2e2d0 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46  signed int prepF
2e2e0 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72  lags, /* Zero or
2e2f0 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45   more SQLITE_PRE
2e300 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20  PARE_ flags */. 
2e310 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2e320 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2e330 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2e340 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2e350 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2e360 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2e370 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2e380 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2e390 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2e3a0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
2e3b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2e3c0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2e3d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2e3e0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2e3f0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2e400 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2e410 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2e420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e430 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2e440 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2e450 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2e460 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2e470 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2e480 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2e490 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2e4a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2e4b0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2e4c0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2e4d0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2e4e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
2e4f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2e500 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2e510 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2e520 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2e530 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2e540 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2e550 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2e560 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2e570 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2e580 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2e590 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2e5a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2e5b0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2e5c0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2e5d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2e5e0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2e5f0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2e600 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2e610 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2e620 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2e630 65 31 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65  e16_v3(.  sqlite
2e640 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2e650 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2e660 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2e670 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2e680 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2e690 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2e6a0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2e6b0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2e6c0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2e6d0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2e6e0 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65  es. */.  unsigne
2e6f0 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c  d int prepFlags,
2e700 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65   /* Zero or more
2e710 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2e720 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69   flags */.  sqli
2e730 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2e740 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2e750 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2e760 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2e770 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2e780 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2e790 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2e7a0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
2e7b0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
2e7c0 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
2e7d0 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  SQL.** METHOD: s
2e7e0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2e7f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2e800 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  ql(P) interface 
2e810 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2e820 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74  r to a copy of t
2e830 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20  he UTF-8.** SQL 
2e840 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
2e850 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ate [prepared st
2e860 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20  atement] P if P 
2e870 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  was.** created b
2e880 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2e890 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
2e8a0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2e8b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
2e8c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f  epare16_v2()], o
2e8d0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2e8e0 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e  re16_v3()]..** ^
2e8f0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2e900 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65  nded_sql(P) inte
2e910 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2e920 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46  pointer to a UTF
2e930 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  -8.** string con
2e940 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20  taining the SQL 
2e950 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 64  text of prepared
2e960 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74   statement P wit
2e970 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61  h.** [bound para
2e980 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64  meters] expanded
2e990 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2e9a0 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c  3_normalized_sql
2e9b0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2e9c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2e9d0 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74  to a UTF-8.** st
2e9e0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
2e9f0 74 68 65 20 6e 6f 72 6d 61 6c 69 7a 65 64 20 53  the normalized S
2ea00 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61  QL text of prepa
2ea10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 2e  red statement P.
2ea20 20 20 54 68 65 0a 2a 2a 20 73 65 6d 61 6e 74 69    The.** semanti
2ea30 63 73 20 75 73 65 64 20 74 6f 20 6e 6f 72 6d 61  cs used to norma
2ea40 6c 69 7a 65 20 61 20 53 51 4c 20 73 74 61 74 65  lize a SQL state
2ea50 6d 65 6e 74 20 61 72 65 20 75 6e 73 70 65 63 69  ment are unspeci
2ea60 66 69 65 64 20 61 6e 64 20 73 75 62 6a 65 63 74  fied and subject
2ea70 0a 2a 2a 20 74 6f 20 63 68 61 6e 67 65 2e 20 20  .** to change.  
2ea80 41 74 20 61 20 6d 69 6e 69 6d 75 6d 2c 20 6c 69  At a minimum, li
2ea90 74 65 72 61 6c 20 76 61 6c 75 65 73 20 77 69 6c  teral values wil
2eaa0 6c 20 62 65 20 72 65 70 6c 61 63 65 64 20 77 69  l be replaced wi
2eab0 74 68 20 73 75 69 74 61 62 6c 65 0a 2a 2a 20 70  th suitable.** p
2eac0 6c 61 63 65 68 6f 6c 64 65 72 73 2e 0a 2a 2a 0a  laceholders..**.
2ead0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2eae0 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20  , if a prepared 
2eaf0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65  statement is cre
2eb00 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  ated using the S
2eb10 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45  QL.** text "SELE
2eb20 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e  CT $abc,:xyz" an
2eb30 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24  d if parameter $
2eb40 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20  abc is bound to 
2eb50 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20  integer 2345.** 
2eb60 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78  and parameter :x
2eb70 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74  yz is unbound, t
2eb80 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  hen sqlite3_sql(
2eb90 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
2eba0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2ebb0 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61  ring, "SELECT $a
2ebc0 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c  bc,:xyz" but sql
2ebd0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2ebe0 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  l().** will retu
2ebf0 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c  rn "SELECT 2345,
2ec00 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  NULL".)^.**.** ^
2ec10 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2ec20 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72  nded_sql() inter
2ec30 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
2ec40 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
2ec50 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61  t memory.** is a
2ec60 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64  vailable to hold
2ec70 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20   the result, or 
2ec80 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f  if the result wo
2ec90 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a  uld exceed the.*
2eca0 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74  * the maximum st
2ecb0 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65  ring length dete
2ecc0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53  rmined by the [S
2ecd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2ece0 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  TH]..**.** ^The 
2ecf0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
2ed00 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
2ed10 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69  e-time option li
2ed20 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
2ed30 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65  .** bound parame
2ed40 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20  ter expansions. 
2ed50 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d   ^The [SQLITE_OM
2ed60 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  IT_TRACE] compil
2ed70 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
2ed80 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f   causes sqlite3_
2ed90 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74  expanded_sql() t
2eda0 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  o always return 
2edb0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2edc0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
2edd0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c  d by sqlite3_sql
2ede0 28 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (P) and sqlite3_
2edf0 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50  normalized_sql(P
2ee00 29 0a 2a 2a 20 61 72 65 20 6d 61 6e 61 67 65 64  ).** are managed
2ee10 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 61   by SQLite and a
2ee20 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
2ee30 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20   freed when the 
2ee40 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2ee50 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2ee60 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69  ed..** ^The stri
2ee70 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ng returned by s
2ee80 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2ee90 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f  sql(P), on the o
2eea0 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73  ther hand,.** is
2eeb0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2eec0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2eed0 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72  ] and must be fr
2eee0 65 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ee by the applic
2eef0 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73  ation.** by pass
2ef00 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
2ef10 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63  e3_free()]..*/.c
2ef20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2ef30 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
2ef40 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61  tmt *pStmt);.cha
2ef50 72 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  r *sqlite3_expan
2ef60 64 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  ded_sql(sqlite3_
2ef70 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 6f  stmt *pStmt);.co
2ef80 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2ef90 33 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c  3_normalized_sql
2efa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2efb0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2efc0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2efd0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
2efe0 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
2eff0 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54   Database.** MET
2f000 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2f010 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2f020 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2f030 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
2f040 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2f050 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
2f060 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
2f070 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f080 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
2f090 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
2f0a0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
2f0b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2f0c0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
2f0d0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
2f0e0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2f0f0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
2f100 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
2f110 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
2f120 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
2f130 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
2f140 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
2f150 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
2f160 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2f170 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
2f180 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
2f190 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
2f1a0 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
2f1b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
2f1c0 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
2f1d0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
2f1e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
2f1f0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
2f200 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
2f210 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
2f220 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
2f230 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
2f240 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
2f250 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
2f260 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
2f270 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2f280 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2f290 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2f2a0 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
2f2b0 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
2f2c0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
2f2d0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
2f2e0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
2f2f0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
2f300 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
2f310 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
2f320 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
2f330 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
2f340 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
2f350 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
2f360 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2f370 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2f380 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
2f390 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
2f3a0 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
2f3b0 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
2f3c0 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
2f3d0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
2f3e0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
2f3f0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
2f400 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
2f410 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
2f420 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
2f430 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
2f440 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
2f450 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
2f460 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2f470 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
2f480 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
2f490 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
2f4a0 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
2f4b0 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
2f4c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f4d0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
2f4e0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
2f4f0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
2f500 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2f510 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20  les on disk..** 
2f520 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2f530 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74  t_readonly() int
2f540 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2f550 72 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20  rue for [BEGIN] 
2f560 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d  since.** [BEGIN]
2f570 20 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74   merely sets int
2f580 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74  ernal flags, but
2f590 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49   the [BEGIN|BEGI
2f5a0 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64  N IMMEDIATE] and
2f5b0 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  .** [BEGIN|BEGIN
2f5c0 20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d   EXCLUSIVE] comm
2f5d0 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68  ands do touch th
2f5e0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73  e database and s
2f5f0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  o.** sqlite3_stm
2f600 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74  t_readonly() ret
2f610 75 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74  urns false for t
2f620 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a  hose commands..*
2f630 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2f640 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
2f650 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2f660 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f670 46 3a 20 51 75 65 72 79 20 54 68 65 20 45 58 50  F: Query The EXP
2f680 4c 41 49 4e 20 53 65 74 74 69 6e 67 20 46 6f 72  LAIN Setting For
2f690 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2f6a0 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
2f6b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f6c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f6d0 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e 28  _stmt_isexplain(
2f6e0 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
2f6f0 75 72 6e 73 20 31 20 69 66 20 74 68 65 0a 2a 2a  urns 1 if the.**
2f700 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2f710 65 6e 74 20 53 20 69 73 20 61 6e 20 45 58 50 4c  ent S is an EXPL
2f720 41 49 4e 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f  AIN statement, o
2f730 72 20 32 20 69 66 20 74 68 65 0a 2a 2a 20 73 74  r 2 if the.** st
2f740 61 74 65 6d 65 6e 74 20 53 20 69 73 20 61 6e 20  atement S is an 
2f750 45 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c  EXPLAIN QUERY PL
2f760 41 4e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  AN..** ^The sqli
2f770 74 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61  te3_stmt_isexpla
2f780 69 6e 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  in(S) interface 
2f790 72 65 74 75 72 6e 73 20 30 20 69 66 20 53 20 69  returns 0 if S i
2f7a0 73 0a 2a 2a 20 61 6e 20 6f 72 64 69 6e 61 72 79  s.** an ordinary
2f7b0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 20   statement or a 
2f7c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
2f7d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2f7e0 74 5f 69 73 65 78 70 6c 61 69 6e 28 73 71 6c 69  t_isexplain(sqli
2f7f0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2f800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f810 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2f820 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2f830 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
2f840 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
2f850 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2f860 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2f870 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
2f880 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2f890 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2f8a0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2f8b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
2f8c0 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
2f8d0 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
2f8e0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2f8f0 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
2f900 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f  s neither run to
2f910 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74   completion (ret
2f920 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2f930 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c  _DONE] from [sql
2f940 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e  ite3_step(S)]) n
2f950 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  or.** been reset
2f960 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2f970 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
2f980 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2f990 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
2f9a0 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
2f9b0 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
2f9c0 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
2f9d0 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
2f9e0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
2f9f0 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
2fa00 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
2fa10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2fa20 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
2fa30 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2fa40 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2fa50 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
2fa60 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2fa70 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2fa80 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
2fa90 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
2faa0 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
2fab0 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
2fac0 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
2fad0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
2fae0 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
2faf0 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
2fb00 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
2fb10 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
2fb20 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
2fb30 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
2fb40 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
2fb50 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
2fb60 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
2fb70 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
2fb80 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
2fb90 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
2fba0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2fbb0 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
2fbc0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2fbd0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
2fbe0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
2fbf0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2fc00 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
2fc10 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
2fc20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2fc30 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
2fc40 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2fc50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2fc60 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
2fc70 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
2fc80 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
2fc90 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
2fca0 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
2fcb0 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
2fcc0 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
2fcd0 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
2fce0 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
2fcf0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2fd00 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
2fd10 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
2fd20 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2fd30 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
2fd40 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
2fd50 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
2fd60 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
2fd70 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
2fd80 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
2fd90 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
2fda0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2fdb0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2fdc0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
2fdd0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
2fde0 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
2fdf0 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
2fe00 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2fe10 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2fe20 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
2fe30 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
2fe40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
2fe50 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
2fe60 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
2fe70 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
2fe80 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2fe90 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65  ite3_value.  The
2fea0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2feb0 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66  ue_dup()] interf
2fec0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2fed0 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e  to construct a n
2fee0 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64  ew .** protected
2fef0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66   sqlite3_value f
2ff00 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  rom an unprotect
2ff10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ff20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
2ff30 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
2ff40 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
2ff50 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
2ff60 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
2ff70 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
2ff80 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
2ff90 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
2ffa0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2ffb0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
2ffc0 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
2ffd0 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
2ffe0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2fff0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
30000 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
30010 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
30020 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
30030 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
30040 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
30050 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
30060 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
30070 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
30080 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
30090 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
300a0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
300b0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
300c0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
300d0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
300e0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
300f0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
30100 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
30110 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
30120 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
30130 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
30140 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
30150 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
30160 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
30170 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
30180 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
30190 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
301a0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
301b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
301c0 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
301d0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
301e0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
301f0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
30200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
30210 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
30220 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
30230 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
30240 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
30250 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
30260 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
30270 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
30280 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
30290 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
302a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
302b0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
302c0 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
302d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
302e0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
302f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
30300 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
30310 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
30320 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
30330 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
30340 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
30350 64 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a  d as arguments.*
30360 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  * to [sqlite3_re
30370 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b  sult_value()], [
30380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
30390 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  ue()], and.** [s
303a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
303b0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
303c0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
303d0 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
303e0 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
303f0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
30400 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
30410 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
30420 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
30430 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
30440 65 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33  e3_value sqlite3
30450 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
30460 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
30470 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
30480 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
30490 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
304a0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
304b0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
304c0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
304d0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
304e0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
304f0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
30500 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
30510 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
30520 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
30530 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30540 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
30550 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
30560 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
30570 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
30580 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
30590 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
305a0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
305b0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
305c0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
305d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
305e0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
305f0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
30600 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
30610 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
30620 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
30630 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
30640 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
30650 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
30660 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
30670 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
30680 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
30690 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
306a0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
306b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
306c0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
306d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
306e0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
306f0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
30700 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
30710 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
30720 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
30730 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
30740 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
30750 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
30760 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45  r binding}.** ME
30770 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30780 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  mt.**.** ^(In th
30790 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
307a0 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
307b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
307c0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
307d0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
307e0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
307f0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
30800 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
30810 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
30820 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
30830 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
30840 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
30850 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
30860 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
30870 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
30880 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
30890 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
308a0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
308b0 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
308c0 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
308d0 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
308e0 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
308f0 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
30900 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
30910 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
30920 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
30930 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
30940 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
30950 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
30960 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
30970 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
30980 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
30990 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
309a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
309b0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
309c0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
309d0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
309e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
309f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
30a00 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
30a10 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
30a20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
30a30 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
30a40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
30a50 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
30a60 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
30a70 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
30a80 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
30a90 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
30aa0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
30ab0 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
30ac0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
30ad0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
30ae0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
30af0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
30b00 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
30b10 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
30b20 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
30b30 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
30b40 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
30b50 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
30b60 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
30b70 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
30b80 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
30b90 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30ba0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
30bb0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
30bc0 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
30bd0 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
30be0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
30bf0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
30c00 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
30c10 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
30c20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
30c30 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
30c40 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
30c50 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
30c60 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
30c70 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
30c80 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
30c90 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
30ca0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
30cb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
30cc0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
30cd0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
30ce0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
30cf0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
30d00 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
30d10 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
30d20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
30d30 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
30d40 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
30d50 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
30d60 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
30d70 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
30d80 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
30d90 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
30da0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
30db0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
30dc0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
30dd0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
30de0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
30df0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
30e00 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
30e10 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
30e20 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
30e30 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
30e40 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
30e50 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
30e60 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
30e70 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
30e80 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
30e90 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
30ea0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
30eb0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
30ec0 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
30ed0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
30ee0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
30ef0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
30f00 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
30f10 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
30f20 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
30f30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
30f40 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
30f50 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
30f60 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
30f70 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
30f80 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
30f90 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
30fa0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
30fb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
30fc0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
30fd0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f  _bind_text16() o
30fe0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
30ff0 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20  ext64() then.** 
31000 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
31010 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
31020 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
31030 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
31040 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
31050 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
31060 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
31070 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
31080 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
31090 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
310a0 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
310b0 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
310c0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
310d0 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
310e0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
310f0 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
31100 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
31110 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
31120 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
31130 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
31140 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
31150 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
31160 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
31170 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
31180 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e  t to the BLOB an
31190 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67  d string binding
311a0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
311b0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
311c0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
311d0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
311e0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
311f0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
31200 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
31210 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
31220 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
31230 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
31240 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
31250 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  f the call to th
31260 65 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73  e bind API fails
31270 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 65 20  ,.** except the 
31280 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 6e 6f  destructor is no
31290 74 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  t called if the 
312a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
312b0 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  is a NULL.** poi
312c0 6e 74 65 72 20 6f 72 20 74 68 65 20 66 6f 75 72  nter or the four
312d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
312e0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 20 5e 49 66  negative..** ^If
312f0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
31300 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
31310 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
31320 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
31330 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
31340 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
31350 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
31360 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
31370 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
31380 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
31390 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
313a0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
313b0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
313c0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
313d0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
313e0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
313f0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
31400 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
31410 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
31420 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
31430 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
31440 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
31450 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
31460 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
31470 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
31480 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
31490 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
314a0 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
314b0 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
314c0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
314d0 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
314e0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
314f0 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
31500 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
31510 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
31520 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
31530 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
31540 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
31550 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
31560 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
31570 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
31580 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
31590 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
315a0 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
315b0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
315c0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
315d0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
315e0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
315f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31600 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
31610 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
31620 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
31630 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
31640 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
31650 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
31660 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
31670 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
31680 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
31690 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
316a0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
316b0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
316c0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
316d0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
316e0 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
316f0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
31700 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
31710 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
31720 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
31730 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
31740 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
31750 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
31760 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
31770 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
31780 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
31790 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
317a0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OB..**.** ^The s
317b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
317c0 74 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72  ter(S,I,P,T,D) r
317d0 6f 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68  outine causes th
317e0 65 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e I-th parameter
317f0 20 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   in.** [prepared
31800 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f   statement] S to
31810 20 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c   have an SQL val
31820 75 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20  ue of NULL, but 
31830 74 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73  to also be.** as
31840 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
31850 65 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74  e pointer P of t
31860 79 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69  ype T.  ^D is ei
31870 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
31880 74 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e  ter or.** a poin
31890 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63  ter to a destruc
318a0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72  tor function for
318b0 20 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c   P. ^SQLite will
318c0 20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64   invoke the.** d
318d0 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68  estructor D with
318e0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
318f0 6e 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20  nt of P when it 
31900 69 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  is finished usin
31910 67 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70  g.** P.  The T p
31920 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
31930 62 65 20 61 20 73 74 61 74 69 63 20 73 74 72 69  be a static stri
31940 6e 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61  ng, preferably a
31950 20 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72   string.** liter
31960 61 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f  al. The sqlite3_
31970 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72  bind_pointer() r
31980 6f 75 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f  outine is part o
31990 66 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65  f the.** [pointe
319a0 72 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66  r passing interf
319b0 61 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53  ace] added for S
319c0 51 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a  QLite 3.20.0..**
319d0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
319e0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
319f0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
31a00 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
31a10 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
31a20 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
31a30 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
31a40 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
31a50 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
31a60 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
31a70 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
31a80 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
31a90 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
31aa0 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
31ab0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
31ac0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
31ad0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
31ae0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
31af0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
31b00 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
31b10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
31b20 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
31b30 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
31b40 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
31b50 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
31b60 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
31b70 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
31b80 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
31b90 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31ba0 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
31bb0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
31bc0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
31bd0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
31be0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
31bf0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
31c00 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
31c10 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
31c20 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
31c30 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
31c40 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
31c50 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
31c60 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
31c70 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
31c80 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
31c90 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
31ca0 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
31cb0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
31cc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
31cd0 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
31ce0 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
31cf0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
31d00 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
31d10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
31d20 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
31d30 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
31d40 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
31d50 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
31d60 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
31d70 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
31d80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
31d90 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
31da0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
31db0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
31dc0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
31dd0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
31de0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
31df0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
31e00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31e10 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
31e20 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
31e30 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
31e40 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73  e3_bind_blob64(s
31e50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31e60 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
31e70 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
31e80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31e90 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
31ea0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
31eb0 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
31ec0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31ed0 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
31ee0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
31ef0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
31f00 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
31f10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
31f20 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
31f30 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
31f40 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
31f50 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
31f60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31f70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
31f80 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
31f90 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74  _stmt*,int,const
31fa0 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28   char*,int,void(
31fb0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
31fc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
31fd0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
31fe0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
31ff0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
32000 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
32010 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
32020 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
32030 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
32040 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
32050 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
32060 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
32070 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
32080 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
32090 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ing);.int sqlite
320a0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
320b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
320c0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
320d0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
320e0 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
320f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
32100 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73  int, void*, cons
32110 74 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28  t char*,void(*)(
32120 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
32130 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
32140 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
32150 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69  , int, int n);.i
32160 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
32170 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74  zeroblob64(sqlit
32180 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
32190 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
321a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
321b0 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
321c0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54  arameters.** MET
321d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
321e0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
321f0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
32200 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
32210 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
32220 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
32230 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32240 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
32250 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
32260 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
32270 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
32280 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
32290 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
322a0 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
322b0 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
322c0 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
322d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
322e0 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
322f0 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
32300 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
32310 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
32320 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
32330 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
32340 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
32350 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
32360 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
32370 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
32380 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
32390 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
323a0 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
323b0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
323c0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
323d0 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
323e0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
323f0 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
32400 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
32410 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
32420 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
32430 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
32440 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
32450 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
32460 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
32470 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
32480 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
32490 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
324a0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
324b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
324c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
324d0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
324e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48  arameter.** METH
324f0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
32500 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32510 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
32520 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
32530 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
32540 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
32550 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
32560 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
32570 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32580 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
32590 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
325a0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
325b0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
325c0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
325d0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
325e0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
325f0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
32600 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
32610 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
32620 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
32630 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
32640 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
32650 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
32660 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
32670 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
32680 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
32690 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
326a0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
326b0 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
326c0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
326d0 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
326e0 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
326f0 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
32700 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
32710 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
32720 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
32730 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
32740 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
32750 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
32760 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
32770 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
32780 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
32790 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
327a0 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
327b0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
327c0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
327d0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
327e0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
327f0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
32800 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
32810 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
32820 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
32830 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73  pare16()],.** [s
32840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32850 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  _v2()], or [sqli
32860 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
32870 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
32880 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
32890 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
328a0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
328b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
328c0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
328d0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
328e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
328f0 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
32900 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
32910 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
32920 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
32930 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
32940 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
32950 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
32960 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
32970 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32980 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
32990 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
329a0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
329b0 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
329c0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
329d0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
329e0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
329f0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
32a00 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
32a10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
32a20 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
32a30 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
32a40 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
32a50 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
32a60 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
32a70 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
32a80 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
32a90 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
32aa0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
32ab0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
32ac0 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
32ad0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
32ae0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
32af0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
32b00 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
32b10 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a  repare16_v3()]..
32b20 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
32b30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
32b40 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
32b50 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
32b60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
32b70 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
32b80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
32b90 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e  rameter_name()].
32ba0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32bb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
32bc0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
32bd0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
32be0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
32bf0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
32c00 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
32c10 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
32c20 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
32c30 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32c40 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
32c50 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
32c60 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
32c70 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
32c80 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
32c90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
32ca0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
32cb0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
32cc0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
32cd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
32ce0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
32cf0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
32d00 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
32d10 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
32d20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
32d30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32d40 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
32d50 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
32d60 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
32d70 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32d80 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
32d90 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
32da0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
32db0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
32dc0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
32dd0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74  tatement]. ^If t
32de0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
32df0 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e  rns 0, that mean
32e00 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61  s the .** [prepa
32e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72  red statement] r
32e20 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28  eturns no data (
32e30 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
32e40 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f  UPDATE])..** ^Ho
32e50 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61  wever, just beca
32e60 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  use this routine
32e70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74   returns a posit
32e80 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20  ive number does 
32e90 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  not.** mean that
32ea0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77   one or more row
32eb0 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62  s of data will b
32ec0 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20  e returned.  ^A 
32ed0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
32ee0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  .** will always 
32ef0 68 61 76 65 20 61 20 70 6f 73 69 74 69 76 65 20  have a positive 
32f00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
32f10 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e  ount() but depen
32f20 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57  ding on the.** W
32f30 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
32f40 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20  traints and the 
32f50 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69  table content, i
32f60 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e  t might return n
32f70 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65  o rows..**.** Se
32f80 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
32f90 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
32fa0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
32fb0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
32fc0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
32fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32fe0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
32ff0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
33000 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
33010 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
33020 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
33030 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
33040 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
33050 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
33060 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
33070 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
33080 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
33090 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
330a0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
330b0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
330c0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
330d0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
330e0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
330f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
33100 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
33110 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
33120 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
33130 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
33140 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
33150 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
33160 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33170 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
33180 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
33190 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
331a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
331b0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
331c0 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
331d0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
331e0 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
331f0 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
33200 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
33210 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
33220 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
33230 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33240 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
33250 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
33260 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
33270 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
33280 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
33290 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
332a0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
332b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
332c0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
332d0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
332e0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
332f0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
33300 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
33310 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
33320 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
33330 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
33340 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
33350 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
33360 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
33370 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
33380 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
33390 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
333a0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
333b0 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
333c0 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
333d0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
333e0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
333f0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
33400 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
33410 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
33420 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
33430 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
33440 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
33450 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
33460 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
33470 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
33480 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
33490 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
334a0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
334b0 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
334c0 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
334d0 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
334e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
334f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
33500 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
33510 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
33520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
33530 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
33540 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
33550 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
33560 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
33570 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
33580 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33590 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
335a0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
335b0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
335c0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
335d0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
335e0 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
335f0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
33600 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
33610 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
33620 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
33630 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
33640 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
33650 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
33660 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
33670 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
33680 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
33690 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
336a0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
336b0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
336c0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
336d0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
336e0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
336f0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
33700 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
33710 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
33720 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
33730 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
33740 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
33750 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
33760 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
33770 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
33780 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
33790 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
337a0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
337b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
337c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
337d0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
337e0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
337f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
33800 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
33810 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
33820 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
33830 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
33840 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
33850 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
33860 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
33870 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
33880 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
33890 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
338a0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
338b0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
338c0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
338d0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
338e0 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
338f0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
33900 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33910 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
33920 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
33930 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
33940 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
33950 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
33960 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
33970 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
33980 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
33990 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
339a0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
339b0 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
339c0 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
339d0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
339e0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
339f0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
33a00 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
33a10 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
33a20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
33a30 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
33a40 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
33a50 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
33a60 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
33a70 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
33a80 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
33a90 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
33aa0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
33ab0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
33ac0 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
33ad0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
33ae0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
33af0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
33b00 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
33b10 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
33b20 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
33b30 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
33b40 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
33b50 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
33b60 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
33b70 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
33b80 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
33b90 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
33ba0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
33bb0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
33bc0 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
33bd0 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
33be0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
33bf0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
33c00 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
33c10 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
33c20 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
33c30 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
33c40 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
33c50 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
33c60 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
33c70 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
33c80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
33c90 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
33ca0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
33cb0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
33cc0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
33cd0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
33ce0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
33cf0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
33d00 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
33d10 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
33d20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
33d30 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
33d40 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
33d50 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
33d60 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
33d70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33d80 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
33d90 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
33da0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
33db0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
33dc0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
33dd0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
33de0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
33df0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
33e00 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
33e10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
33e20 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
33e30 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
33e40 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
33e50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
33e60 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
33e70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
33e80 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
33e90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33ea0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
33eb0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
33ec0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
33ed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
33ee0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
33ef0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
33f00 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
33f10 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
33f20 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
33f30 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
33f40 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
33f50 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
33f60 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
33f70 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
33f80 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  stmt.**.** ^(The
33f90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
33fa0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
33fb0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
33fc0 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
33fd0 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
33fe0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
33ff0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
34000 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
34010 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
34020 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
34030 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
34040 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
34050 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
34060 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
34070 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
34080 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
34090 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
340a0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
340b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
340c0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
340d0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
340e0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
340f0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
34100 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
34110 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
34120 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
34130 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
34140 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
34150 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
34160 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
34170 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
34180 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
34190 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
341a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
341b0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
341c0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
341d0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
341e0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
341f0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
34200 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
34210 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
34220 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
34230 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
34240 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
34250 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
34260 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
34270 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
34280 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
34290 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
342a0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
342b0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
342c0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
342d0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
342e0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
342f0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
34300 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
34310 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
34320 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
34330 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
34340 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
34350 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
34360 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
34370 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
34380 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
34390 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
343a0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
343b0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
343c0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
343d0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
343e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
343f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
34400 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
34410 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
34420 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
34430 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
34440 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
34450 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34460 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
34470 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
34480 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
34490 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  stmt.**.** After
344a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
344b0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
344c0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
344d0 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  any of.** [sqlit
344e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
344f0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
34500 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v3()], [sqlit
34510 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
34520 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
34530 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
34540 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
34550 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
34560 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
34570 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
34580 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
34590 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
345a0 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
345b0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
345c0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
345d0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
345e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
345f0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
34600 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
34610 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
34620 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
34630 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
34640 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
34650 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
34660 65 72 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  er "vX" interfac
34670 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  es.** [sqlite3_p
34680 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
34690 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
346a0 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
346b0 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a  repare16_v3()],.
346c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
346d0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
346e0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
346f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
34700 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
34710 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
34720 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
34730 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
34740 6e 65 77 20 22 76 58 22 20 69 6e 74 65 72 66 61  new "vX" interfa
34750 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
34760 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
34770 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
34780 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
34790 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
347a0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
347b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
347c0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
347d0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
347e0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
347f0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
34800 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
34810 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
34820 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
34830 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
34840 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
34850 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
34860 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
34870 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
34880 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
34890 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
348a0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
348b0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
348c0 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
348d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
348e0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
348f0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
34900 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
34910 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
34920 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
34930 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
34940 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
34950 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
34960 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
34970 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
34980 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
34990 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
349a0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
349b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
349c0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
349d0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
349e0 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
349f0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
34a00 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
34a10 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
34a20 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
34a30 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
34a40 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
34a50 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
34a60 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
34a70 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
34a80 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
34a90 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
34aa0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
34ab0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
34ac0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
34ad0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
34ae0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
34af0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
34b00 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
34b10 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
34b20 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
34b30 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
34b40 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
34b50 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
34b60 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
34b70 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
34b80 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
34b90 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
34ba0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
34bb0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
34bc0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
34bd0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
34be0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
34bf0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
34c00 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
34c10 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
34c20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
34c30 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
34c40 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
34c50 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
34c60 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
34c70 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
34c80 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
34c90 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
34ca0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
34cb0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
34cc0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
34cd0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
34ce0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
34cf0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
34d00 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
34d10 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
34d20 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
34d30 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
34d40 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
34d50 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
34d60 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
34d70 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
34d80 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
34d90 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
34da0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
34db0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
34dc0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
34dd0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
34de0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
34df0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
34e00 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
34e10 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
34e20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
34e30 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
34e40 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
34e50 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
34e60 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
34e70 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
34e80 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
34e90 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
34ea0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
34eb0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
34ec0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
34ed0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
34ee0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
34ef0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
34f00 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
34f10 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
34f20 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
34f30 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
34f40 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
34f50 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
34f60 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
34f70 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
34f80 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
34f90 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
34fa0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
34fb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
34fc0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
34fd0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
34fe0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
34ff0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
35000 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
35010 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
35020 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
35030 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
35040 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
35050 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
35060 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
35070 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
35080 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
35090 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
350a0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
350b0 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
350c0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
350d0 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
350e0 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
350f0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
35100 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
35110 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
35120 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
35130 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
35140 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
35150 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
35160 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
35170 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e  t after [version
35180 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74   3.6.23.1] ([dat
35190 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a  eof:3.6.23.1],.*
351a0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
351b0 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
351c0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
351d0 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
351e0 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
351f0 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
35200 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
35210 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
35220 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
35230 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
35240 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
35250 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
35260 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
35270 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
35280 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
35290 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
352a0 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
352b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
352c0 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
352d0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
352e0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
352f0 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
35300 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
35310 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
35320 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
35330 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
35340 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
35350 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
35360 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
35370 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
35380 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
35390 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
353a0 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
353b0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
353c0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
353d0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
353e0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
353f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
35400 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
35410 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
35420 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
35430 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
35440 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
35450 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
35460 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
35470 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
35480 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
35490 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
354a0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
354b0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
354c0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
354d0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
354e0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
354f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
35500 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
35510 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20  3_prepare_v3()] 
35520 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
35530 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20  are_v2()].** or 
35540 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35550 31 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  16_v2()] or [sql
35560 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
35570 33 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  3()] instead.** 
35580 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
35590 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
355a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
355b0 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
355c0 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
355d0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
355e0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
355f0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
35600 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
35610 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
35620 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 58 22   use of the "vX"
35630 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 72   interfaces is r
35640 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69  ecommended..*/.i
35650 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
35660 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
35670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35680 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
35690 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
356a0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
356b0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
356c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
356d0 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
356e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
356f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
35700 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
35710 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
35720 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
35730 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35740 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
35750 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35760 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
35770 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
35780 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
35790 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
357a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
357b0 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
357c0 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
357d0 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
357e0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
357f0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
35800 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35810 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
35820 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
35830 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
35840 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
35850 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
35860 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
35870 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
35880 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
35890 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
358a0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
358b0 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
358c0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
358d0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
358e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
358f0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
35900 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
35910 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
35920 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
35930 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
35940 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
35950 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
35960 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
35970 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
35980 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
35990 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
359a0 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
359b0 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
359c0 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
359d0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
359e0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
359f0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
35a00 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
35a10 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
35a20 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
35a30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
35a40 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
35a50 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
35a60 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
35a70 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
35a80 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
35a90 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
35aa0 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
35ab0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
35ac0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
35ad0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
35ae0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
35af0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
35b00 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
35b10 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
35b20 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
35b30 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
35b40 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
35b50 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
35b60 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
35b70 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
35b80 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
35b90 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
35ba0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
35bb0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
35bc0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
35bd0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
35be0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
35bf0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
35c00 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
35c10 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
35c20 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
35c30 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
35c40 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
35c50 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
35c60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
35c70 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
35c80 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
35c90 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
35ca0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
35cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
35cc0 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
35cd0 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
35ce0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
35cf0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
35d00 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
35d10 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
35d20 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
35d30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35d40 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
35d50 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
35d60 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
35d70 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
35d80 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
35d90 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
35da0 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62  * <b>Summary:</b
35db0 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  >.** <blockquote
35dc0 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30  ><table border=0
35dd0 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63   cellpadding=0 c
35de0 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a  ellspacing=0>.**
35df0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
35e00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c  te3_column_blob<
35e10 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
35e20 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20  >BLOB result.** 
35e30 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
35e40 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
35e50 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
35e60 64 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a  d>REAL result.**
35e70 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
35e80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f  te3_column_int</
35e90 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
35ea0 33 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72  32-bit INTEGER r
35eb0 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
35ec0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
35ed0 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e  mn_int64</b><td>
35ee0 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74  &rarr;<td>64-bit
35ef0 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a   INTEGER result.
35f00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
35f10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35f20 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  t</b><td>&rarr;<
35f30 74 64 3e 55 54 46 2d 38 20 54 45 58 54 20 72 65  td>UTF-8 TEXT re
35f40 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
35f50 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
35f60 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e  n_text16</b><td>
35f70 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36  &rarr;<td>UTF-16
35f80 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20   TEXT result.** 
35f90 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
35fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c  e3_column_value<
35fb0 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
35fc0 3e 54 68 65 20 72 65 73 75 6c 74 20 61 73 20 61  >The result as a
35fd0 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  n .** [sqlite3_v
35fe0 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74 65 64  alue|unprotected
35ff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
36000 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c  object..** <tr><
36010 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62  td>&nbsp;<td>&nb
36020 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a  sp;<td>&nbsp;.**
36030 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
36040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36050 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
36060 64 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42  d>Size of a BLOB
36070 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38 20 54  .** or a UTF-8 T
36080 45 58 54 20 72 65 73 75 6c 74 20 69 6e 20 62 79  EXT result in by
36090 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  tes.** <tr><td><
360a0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
360b0 5f 62 79 74 65 73 31 36 26 6e 62 73 70 3b 26 6e  _bytes16&nbsp;&n
360c0 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e  bsp;</b>.** <td>
360d0 26 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73  &rarr;&nbsp;&nbs
360e0 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55 54  p;<td>Size of UT
360f0 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20  F-16.** TEXT in 
36100 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  bytes.** <tr><td
36110 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
36120 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26  mn_type</b><td>&
36130 72 61 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74  rarr;<td>Default
36140 0a 2a 2a 20 64 61 74 61 74 79 70 65 20 6f 66 20  .** datatype of 
36150 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f  the result.** </
36160 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  table></blockquo
36170 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74  te>.**.** <b>Det
36180 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20  ails:</b>.**.** 
36190 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
361a0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
361b0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
361c0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
361d0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
361e0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
361f0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
36200 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
36210 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
36220 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
36230 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36240 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
36250 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
36260 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
36270 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
36280 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
36290 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
362a0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
362b0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
362c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
362d0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
362e0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
362f0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
36300 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
36310 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
36320 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
36330 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
36340 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
36350 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
36360 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
36370 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
36380 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
36390 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
363a0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
363b0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
363c0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
363d0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
363e0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
363f0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
36400 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
36410 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
36420 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
36430 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
36440 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
36450 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
36460 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
36470 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
36480 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
36490 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
364a0 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
364b0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
364c0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
364d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
364e0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
364f0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
36500 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
36510 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
36520 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
36530 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
36540 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
36550 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
36560 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
36570 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
36580 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
36590 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
365a0 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
365b0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
365c0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
365d0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
365e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
365f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
36600 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
36610 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
36620 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
36630 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
36640 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
36650 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
36660 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
36670 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
36680 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65  e first six inte
36690 72 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f  rfaces (_blob, _
366a0 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69  double, _int, _i
366b0 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64  nt64, _text, and
366c0 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65 61 63   _text16).** eac
366d0 68 20 72 65 74 75 72 6e 20 74 68 65 20 76 61 6c  h return the val
366e0 75 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  ue of a result c
366f0 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65 63 69  olumn in a speci
36700 66 69 63 20 64 61 74 61 20 66 6f 72 6d 61 74 2e  fic data format.
36710 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 75    If.** the resu
36720 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74  lt column is not
36730 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74 68   initially in th
36740 65 20 72 65 71 75 65 73 74 65 64 20 66 6f 72 6d  e requested form
36750 61 74 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  at (for example,
36760 0a 2a 2a 20 69 66 20 74 68 65 20 71 75 65 72 79  .** if the query
36770 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
36780 67 65 72 20 62 75 74 20 74 68 65 20 73 71 6c 69  ger but the sqli
36790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
367a0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ) interface.** i
367b0 73 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63  s used to extrac
367c0 74 20 74 68 65 20 76 61 6c 75 65 29 20 74 68 65  t the value) the
367d0 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 74  n an automatic t
367e0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ype conversion i
367f0 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a  s performed..**.
36800 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36810 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
36820 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
36830 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
36840 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
36850 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
36860 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
36870 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
36880 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
36890 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
368a0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
368b0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
368c0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
368d0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
368e0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
368f0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20  QLITE_NULL]..** 
36900 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
36910 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
36920 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e 20 62 65  mn_type() can be
36930 20 75 73 65 64 20 74 6f 20 64 65 63 69 64 65 20   used to decide 
36940 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20  which.** of the 
36950 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66  first six interf
36960 61 63 65 20 73 68 6f 75 6c 64 20 62 65 20 75 73  ace should be us
36970 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74 68  ed to extract th
36980 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a  e column value..
36990 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  ** The value ret
369a0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
369b0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
369c0 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
369d0 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d  l if no.** autom
369e0 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72  atic type conver
369f0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
36a00 72 65 64 20 66 6f 72 20 74 68 65 20 76 61 6c 75  red for the valu
36a10 65 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20  e in question.  
36a20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74 79 70 65  .** After a type
36a30 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65   conversion, the
36a40 20 72 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69   result of calli
36a50 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ng sqlite3_colum
36a60 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73 20 75  n_type().** is u
36a70 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f 75 67 68  ndefined, though
36a80 20 68 61 72 6d 6c 65 73 73 2e 20 20 46 75 74 75   harmless.  Futu
36a90 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
36aa0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
36ab0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
36ac0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
36ad0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
36ae0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
36af0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
36b00 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
36b10 20 61 20 42 4c 4f 42 20 6f 72 20 61 20 54 45 58   a BLOB or a TEX
36b20 54 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74  T string, then t
36b30 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
36b40 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20  n_bytes().** or 
36b50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36b60 79 74 65 73 31 36 28 29 20 69 6e 74 65 72 66 61  ytes16() interfa
36b70 63 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ces can be used 
36b80 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
36b90 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74   size.** of that
36ba0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
36bb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
36bc0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
36bd0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
36be0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
36bf0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
36c00 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
36c10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
36c20 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
36c30 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
36c40 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
36c50 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
36c60 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
36c70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36c80 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
36c90 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
36ca0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
36cb0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
36cc0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
36cd0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
36ce0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
36cf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36d00 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
36d10 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
36d20 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
36d30 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
36d40 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
36d50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
36d60 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
36d70 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
36d80 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
36d90 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
36da0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36db0 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
36dc0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
36dd0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
36de0 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
36df0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
36e00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36e10 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
36e20 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
36e30 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
36e40 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
36e50 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
36e60 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
36e70 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
36e80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36e90 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
36ea0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
36eb0 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
36ec0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
36ed0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
36ee0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
36ef0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
36f00 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
36f10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
36f20 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
36f30 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
36f40 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
36f50 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
36f60 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
36f70 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
36f80 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
36f90 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
36fa0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
36fb0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
36fc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36fd0 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
36fe0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
36ff0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
37000 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
37010 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
37020 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
37030 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
37040 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
37050 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
37060 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
37070 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
37080 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
37090 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
370a0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
370b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
370c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
370d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
370e0 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
370f0 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
37100 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
37110 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
37120 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
37130 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
37140 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
37150 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
37160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
37170 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
37180 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
37190 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
371a0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
371b0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
371c0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
371d0 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
371e0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
371f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
37200 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e  r..**.** <b>Warn
37210 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62  ing:</b> ^The ob
37220 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
37230 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
37240 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
37250 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
37260 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
37270 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c  bject.  In a mul
37280 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72  tithreaded envir
37290 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e  onment,.** an un
372a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
372b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
372c0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
372d0 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b  safely with.** [
372e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
372f0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
37300 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
37310 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
37320 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
37330 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
37340 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
37350 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
37360 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
37370 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
37380 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
37390 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
373a0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
373b0 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
373c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
373d0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
373e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
373f0 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f  ()], the behavio
37400 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  r is not threads
37410 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74  afe..** Hence, t
37420 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
37430 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  n_value() interf
37440 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c  ace.** is normal
37450 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77  ly only useful w
37460 69 74 68 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d  ithin the implem
37470 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20  entation of .** 
37480 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
37490 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
374a0 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ns] or [virtual 
374b0 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74  tables], not wit
374c0 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  hin.** top-level
374d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
374e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65  e..**.** The the
374f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
37500 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
37510 72 74 20 74 68 65 20 64 61 74 61 74 79 70 65 20  rt the datatype 
37520 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  of the result..*
37530 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  * ^For example, 
37540 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
37550 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
37560 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
37570 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
37580 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
37590 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
375a0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
375b0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
375c0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
375d0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
375e0 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
375f0 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
37600 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
37610 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
37620 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
37630 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
37640 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
37650 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
37660 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
37670 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
37680 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
37690 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
376a0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
376b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
376c0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
376d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
376e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
376f0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
37700 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
37710 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
37720 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
37730 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
37740 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
37750 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
37760 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
37770 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
37780 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
37790 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
377a0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
377b0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
377c0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
377d0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
377e0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
377f0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
37800 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
37810 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
37820 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
37830 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
37840 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
37850 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
37860 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
37870 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
37880 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
37890 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
378a0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
378b0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
378c0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
378d0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
378e0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
378f0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
37900 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
37910 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
37920 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
37930 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
37940 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
37950 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
37960 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
37970 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
37980 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
37990 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
379a0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
379b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
379c0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
379d0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
379e0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
379f0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
37a00 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
37a10 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
37a20 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
37a30 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
37a40 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
37a50 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
37a60 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
37a70 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
37a80 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
37a90 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
37aa0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
37ab0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
37ac0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
37ad0 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
37ae0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37af0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
37b00 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
37b10 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
37b20 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
37b30 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
37b40 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
37b50 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
37b60 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
37b70 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
37b80 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
37b90 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
37ba0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
37bb0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
37bc0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
37bd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
37be0 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
37bf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
37c00 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
37c10 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
37c20 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
37c30 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
37c40 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
37c50 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
37c60 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
37c70 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
37c80 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
37c90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
37ca0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
37cb0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
37cc0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
37cd0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
37ce0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
37cf0 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
37d00 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
37d10 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
37d20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
37d30 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
37d40 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
37d50 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
37d60 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
37d70 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
37d80 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
37d90 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
37da0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
37db0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
37dc0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
37dd0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
37de0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
37df0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
37e00 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
37e10 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
37e20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
37e30 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
37e40 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
37e50 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
37e60 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
37e70 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
37e80 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
37e90 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
37ea0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
37eb0 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
37ec0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
37ed0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
37ee0 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
37ef0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
37f00 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
37f10 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
37f20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
37f30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
37f40 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  t policy is to i
37f50 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
37f60 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
37f70 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
37f80 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
37f90 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
37fa0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
37fb0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
37fc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
37fd0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
37fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
37ff0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
38000 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
38010 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
38020 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
38030 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
38040 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
38050 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
38060 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
38070 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
38080 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
38090 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
380a0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
380b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
380c0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
380d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
380e0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
380f0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
38100 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
38110 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
38120 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
38130 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
38140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
38150 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
38160 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
38170 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
38180 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
38190 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
381a0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
381b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
381c0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
381d0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
381e0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
381f0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
38200 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
38210 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
38220 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
38230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
38240 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
38250 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
38260 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
38270 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
38280 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
38290 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
382a0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
382b0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
382c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
382d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
382e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
382f0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
38300 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
38310 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
38320 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
38330 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
38340 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70 61 73 73  ly.  Do not pass
38350 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
38360 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
38370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
38380 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
38390 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
383a0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
383b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
383c0 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73  **.** As long as
383d0 20 74 68 65 20 69 6e 70 75 74 20 70 61 72 61 6d   the input param
383e0 65 74 65 72 73 20 61 72 65 20 63 6f 72 72 65 63  eters are correc
383f0 74 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t, these routine
38400 73 20 77 69 6c 6c 20 6f 6e 6c 79 0a 2a 2a 20 66  s will only.** f
38410 61 69 6c 20 69 66 20 61 6e 20 6f 75 74 2d 6f 66  ail if an out-of
38420 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72 20 6f 63  -memory error oc
38430 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 66 6f  curs during a fo
38440 72 6d 61 74 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  rmat conversion.
38450 0a 2a 2a 20 4f 6e 6c 79 20 74 68 65 20 66 6f 6c  .** Only the fol
38460 6c 6f 77 69 6e 67 20 73 75 62 73 65 74 20 6f 66  lowing subset of
38470 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
38480 73 75 62 6a 65 63 74 20 74 6f 20 6f 75 74 2d 6f  subject to out-o
38490 66 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 65 72 72 6f  f-memory.** erro
384a0 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
384b0 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63  * <li> sqlite3_c
384c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 0a 2a 2a 20  olumn_blob().** 
384d0 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  <li> sqlite3_col
384e0 75 6d 6e 5f 74 65 78 74 28 29 0a 2a 2a 20 3c 6c  umn_text().** <l
384f0 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  i> sqlite3_colum
38500 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 3c 6c  n_text16().** <l
38510 69 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  i> sqlite3_colum
38520 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 3c 6c 69  n_bytes().** <li
38530 3e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  > sqlite3_column
38540 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 3c 2f  _bytes16().** </
38550 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ul>.**.** If an 
38560 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 65 72  out-of-memory er
38570 72 6f 72 20 6f 63 63 75 72 73 2c 20 74 68 65 6e  ror occurs, then
38580 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
38590 65 20 66 72 6f 6d 20 74 68 65 73 65 0a 2a 2a 20  e from these.** 
385a0 72 6f 75 74 69 6e 65 73 20 69 73 20 74 68 65 20  routines is the 
385b0 73 61 6d 65 20 61 73 20 69 66 20 74 68 65 20 63  same as if the c
385c0 6f 6c 75 6d 6e 20 68 61 64 20 63 6f 6e 74 61 69  olumn had contai
385d0 6e 65 64 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 20  ned an SQL NULL 
385e0 76 61 6c 75 65 2e 0a 2a 2a 20 56 61 6c 69 64 20  value..** Valid 
385f0 53 51 4c 20 4e 55 4c 4c 20 72 65 74 75 72 6e 73  SQL NULL returns
38600 20 63 61 6e 20 62 65 20 64 69 73 74 69 6e 67 75   can be distingu
38610 69 73 68 65 64 20 66 72 6f 6d 20 6f 75 74 2d 6f  ished from out-o
38620 66 2d 6d 65 6d 6f 72 79 20 65 72 72 6f 72 73 0a  f-memory errors.
38630 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 74  ** by invoking t
38640 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  he [sqlite3_errc
38650 6f 64 65 28 29 5d 20 69 6d 6d 65 64 69 61 74 65  ode()] immediate
38660 6c 79 20 61 66 74 65 72 20 74 68 65 20 73 75 73  ly after the sus
38670 70 65 63 74 0a 2a 2a 20 72 65 74 75 72 6e 20 76  pect.** return v
38680 61 6c 75 65 20 69 73 20 6f 62 74 61 69 6e 65 64  alue is obtained
38690 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 0a   and before any.
386a0 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
386b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
386c0 6c 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  led on the same 
386d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
386e0 74 69 6f 6e 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  tion]..*/.const 
386f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
38700 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
38710 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
38720 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
38730 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e