/ Hex Artifact Content
Login

Artifact f18eef5b101d5f33f98ca43decb1f025c1b629f091ad77fe2190128e93938a5a:


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 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5190: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (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 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
51c0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
51d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (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 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
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 34 3c 3c 38  TE_IOERR | (4<<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 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5280: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<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 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
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 36 3c 3c 38 29 29  _IOERR | (6<<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 54 41 54 20 20 20 20 20  IOERR_FSTAT     
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 37 3c 3c 38 29 29 0a  IOERR | (7<<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 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
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 38 3c 3c 38 29 29 0a 23  OERR | (8<<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 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
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 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<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 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
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 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
53e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53f0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5410: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5430: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5450: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5470: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5480: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5490: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
54a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54b0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
54c0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
54d0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
54e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54f0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5500: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5510: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5530: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5540: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5550: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5570: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5590: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55b0: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55d0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
55e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55f0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
5600: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5610: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5630: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5650: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5670: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5690: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
56a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56b0: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
56c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56d0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56f0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
5700: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5710: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
5720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5730: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5740: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5750: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5770: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5780: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5790: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
57a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57b0: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
57c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
57d0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57f0: 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20  RR_VNODE        
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5810: 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64  RR | (27<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5830: 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20 20  RR_AUTH         
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5850: 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64  RR | (28<<8)).#d
5860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5870: 52 52 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20  RR_BEGIN_ATOMIC 
5880: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5890: 52 52 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64  RR | (29<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58b0: 52 52 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  RR_COMMIT_ATOMIC
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
58d0: 52 52 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64  RR | (30<<8)).#d
58e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58f0: 52 52 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  RR_ROLLBACK_ATOM
5900: 49 43 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45  IC   (SQLITE_IOE
5910: 52 52 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64  RR | (31<<8)).#d
5920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5930: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
5940: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
5950: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5970: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5980: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5990: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
59a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
59b0: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
59c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
59d0: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
59e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5a00: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5a10: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5a20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a30: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5a40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5a50: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5a80: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5a90: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5aa0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ab0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5ac0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5ad0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5ae0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5b00: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5b10: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5b20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b30: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5b40: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5b50: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5b60: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5b80: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5b90: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ba0: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5bc0: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5bd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5be0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5c00: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5c10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5c20: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5c30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c40: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
5c50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5c60: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
5c90: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ca0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
5cb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5cc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5cd0: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
5ce0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5cf0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5d00: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5d10: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
5d20: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5d30: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5d50: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
5d60: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5d70: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
5d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d90: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
5da0: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
5db0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
5dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dd0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
5de0: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
5df0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5e00: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5e10: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e20: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
5e30: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e40: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
5e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5e60: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
5e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5e80: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
5e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ea0: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
5eb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ec0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
5ed0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ee0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
5ef0: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
5f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f10: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
5f20: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f30: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
5f40: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f50: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5f60: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f70: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
5f80: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5fa0: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
5fb0: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
5fc0: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
5fd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5fe0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
5ff0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
6000: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
6010: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
6020: 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50  SQLITE_OK_LOAD_P
6030: 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28  ERMANENTLY     (
6040: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c  SQLITE_OK | (1<<
6050: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
6060: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
6070: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
6080: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
6090: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
60a0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
60b0: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
60c0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
60d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
60f0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
6100: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
6110: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6120: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
6130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6140: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
6150: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
6160: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6170: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6190: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
61a0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
61b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
61c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
61d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61e0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
61f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
6200: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6210: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6230: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
6240: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
6250: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6270: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
6280: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
6290: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62b0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
62c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
62d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62f0: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
6300: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
6310: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6320: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6340: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
6350: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
6360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6390: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
63a0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
63b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
63c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
63d0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
63e0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
63f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6410: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
6420: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
6430: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6450: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
6460: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
6470: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6490: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
64a0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
64b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
64c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
64d0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
64e0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
64f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6510: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
6520: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
6530: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6550: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
6560: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
6570: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6580: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65a0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
65b0: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
65c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
65d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
65e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65f0: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
6600: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
6610: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6620: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6640: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
6650: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
6660: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6670: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6690: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
66a0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
66b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
66c0: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
66d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
66e0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
66f0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
6700: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
6710: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
6720: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6730: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
6740: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
6750: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
6760: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
6770: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
6780: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
6790: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
67a0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
67b0: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
67c0: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
67d0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
67e0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
67f0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
6800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6810: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
6820: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6830: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6840: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6850: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6860: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6870: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6890: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
68a0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
68b0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
68c0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
68d0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
68e0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
68f0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
6900: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
6910: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
6920: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6940: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
6950: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6960: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6970: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6980: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6990: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
69a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
69b0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
69c0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
69d0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
69e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
69f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
6a00: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6a10: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
6a20: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6a30: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
6a40: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
6a50: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
6a60: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6a70: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6a80: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
6a90: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
6aa0: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
6ab0: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
6ac0: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
6ad0: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
6ae0: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
6af0: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
6b00: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
6b10: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
6b20: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
6b30: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
6b40: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
6b50: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
6b60: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
6b70: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
6b80: 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ged.  The SQLITE
6b90: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6ba0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20  LE_WHEN_OPEN.** 
6bb0: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74  flag indicates t
6bc0: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
6bd0: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
6be0: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
6bf0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6c00: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6c10: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6c20: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6c30: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6c40: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
6c50: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
6c60: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
6c70: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
6c80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41  TE_IOCAP_BATCH_A
6ca0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6cb0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 75 6e  eans that the un
6cc0: 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69 6c 65  derlying.** file
6cd0: 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20  system supports 
6ce0: 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65 20 77  doing multiple w
6cf0: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
6d00: 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65 6e 20  atomically when 
6d10: 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65 20 6f  those.** write o
6d20: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 62 72  perations are br
6d30: 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51 4c 49  acketed by [SQLI
6d40: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
6d50: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61 6e 64  TOMIC_WRITE] and
6d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
6d70: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
6d80: 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65 66 69  WRITE]..*/.#defi
6d90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6da0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6db0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6dc0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6dd0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6df0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6e00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6e10: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6e20: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6e30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6e40: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6e50: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6e60: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6e70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6e80: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6e90: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6ea0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6eb0: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6ec0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6ed0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6ee0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6ef0: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6f00: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6f10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6f20: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6f30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6f40: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6f50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6f60: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6f70: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6f80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6f90: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6fa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6fc0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6fe0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6ff0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
7000: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
7010: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
7020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7030: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
7040: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
7050: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
7060: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
7070: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
7080: 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65    0x00002000.#de
7090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
70a0: 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 20  P_BATCH_ATOMIC  
70b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 34           0x00004
70c0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
70d0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
70e0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
70f0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
7100: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
7110: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
7120: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
7130: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
7140: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
7150: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
7160: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
7170: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7180: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
7190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71a0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
71b0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
71c0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
71d0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
71e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
71f0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
7200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7210: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
7220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7230: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
7240: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
7250: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
7260: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
7270: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
7280: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
7290: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
72a0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
72b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
72c0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
72d0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
72e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
72f0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
7300: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
7310: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
7320: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7330: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
7340: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
7350: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
7360: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
7370: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
7380: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
7390: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
73a0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
73b0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
73c0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
73d0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
73e0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
73f0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
7400: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
7410: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
7420: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
7430: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
7440: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
7450: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
7460: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
7470: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7480: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
7490: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
74a0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
74b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
74c0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
74d0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
74e0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
74f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
7500: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
7510: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
7520: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
7530: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
7540: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
7550: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
7560: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
7570: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
7580: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
7590: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
75a0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
75b0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
75c0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
75d0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
75e0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
75f0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7600: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7610: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7620: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7630: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
7640: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
7650: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
7660: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
7670: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
7680: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
7690: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
76a0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
76b0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
76c0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
76d0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
76e0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
76f0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7700: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7710: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7720: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7730: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
7740: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
7750: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
7760: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7770: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
7780: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
7790: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
77a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
77b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
77c0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
77d0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
77e0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
77f0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7800: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7810: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7820: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7830: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
7840: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
7850: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
7860: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
7870: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
7880: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
7890: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
78a0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
78b0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
78c0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
78d0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
78e0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
78f0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7900: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7910: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7920: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7930: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
7940: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
7950: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
7960: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
7970: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
7980: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
7990: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
79a0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
79b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
79c0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
79d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
79e0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
79f0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7a00: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7a10: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7a20: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7a30: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
7a40: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
7a50: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
7a60: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
7a70: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a80: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
7a90: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
7aa0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7ab0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
7ac0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
7ad0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
7ae0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7af0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7b00: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7b10: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7b20: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7b30: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
7b40: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
7b50: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
7b60: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
7b70: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
7b80: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
7b90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7ba0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
7bb0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7bc0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
7bd0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
7be0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7bf0: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7c00: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7c10: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7c20: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7c30: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
7c40: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
7c50: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
7c60: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
7c70: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
7c80: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
7c90: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
7ca0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
7cb0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
7cc0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
7cd0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
7ce0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7cf0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7d00: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7d10: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7d20: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7d30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
7d40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
7d50: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
7d60: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
7d70: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
7d80: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
7d90: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
7da0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
7db0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
7dc0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
7dd0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
7de0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7df0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7e00: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7e10: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7e20: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7e30: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7e40: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7e50: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7e60: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7e70: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
7e80: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
7e90: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7ea0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
7eb0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7ec0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7ed0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7ee0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7ef0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7f00: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7f10: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7f20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7f30: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7f40: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7f50: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7f60: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7f70: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
7f80: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
7f90: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
7fa0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
7fb0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
7fc0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
7fd0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7fe0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7ff0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
8000: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
8010: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
8020: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
8030: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
8040: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
8050: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
8060: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
8070: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
8080: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
8090: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
80a0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
80b0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
80c0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
80d0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
80e0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
80f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
8100: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
8110: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
8120: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
8130: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8140: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
8150: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
8160: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
8170: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
8180: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
8190: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
81a0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
81b0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
81c0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
81d0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
81e0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
81f0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
8200: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
8210: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
8220: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
8230: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
8240: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
8250: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
8260: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
8270: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
8280: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
8290: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
82a0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
82b0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
82c0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
82d0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
82e0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
82f0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
8300: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
8310: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
8320: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
8330: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
8340: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66  own use..** A [f
8350: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8360: 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  des | list of op
8370: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
8380: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
8390: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
83a0: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
83b0: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
83c0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
83d0: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
83e0: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
83f0: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
8400: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
8410: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8420: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
8430: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
8440: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
8450: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
8460: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
8470: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
8480: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
8490: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
84a0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
84b0: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
84c0: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
84d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
84e0: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
84f0: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
8500: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
8510: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
8520: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
8530: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
8540: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
8550: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
8560: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
8570: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
8580: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
8590: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
85a0: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
85b0: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
85c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
85d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
85e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
85f0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
8600: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8610: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
8620: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8630: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
8640: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8650: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
8660: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8670: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
8680: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8690: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
86a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
86b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
86c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
86d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
86e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
86f0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8700: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
8710: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8720: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  NTIAL].** <li> [
8730: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
8740: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
8750: 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  EN].** <li> [SQL
8760: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
8770: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a 2a  AFE_OVERWRITE].*
8780: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8790: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a  OCAP_IMMUTABLE].
87a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
87b0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
87c0: 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IC].** </ul>.**.
87d0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
87e0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
87f0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
8800: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8810: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8820: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8830: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8840: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8850: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
8860: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
8870: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
8880: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
8890: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
88a0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
88b0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
88c0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
88d0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
88e0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
88f0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
8900: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8910: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8920: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8930: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8940: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8950: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
8960: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
8970: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
8980: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
8990: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
89a0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
89b0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
89c0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
89d0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
89e0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
89f0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
8a00: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8a10: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8a20: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8a30: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8a40: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8a50: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
8a60: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
8a70: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
8a80: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
8a90: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
8aa0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
8ab0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
8ac0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
8ad0: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
8ae0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8af0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
8b00: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8b10: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8b20: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8b30: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8b40: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8b50: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
8b60: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8b70: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
8b80: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
8b90: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
8ba0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
8bb0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
8bc0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
8bd0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8be0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8bf0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
8c00: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8c10: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8c20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8c30: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8c40: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8c50: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8c60: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
8c70: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
8c80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8c90: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
8ca0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
8cb0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8cc0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
8cd0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
8ce0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8cf0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
8d00: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8d10: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8d20: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8d30: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8d40: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8d50: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
8d60: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
8d70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
8d80: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
8d90: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
8da0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8db0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
8dc0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8dd0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
8de0: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
8df0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8e00: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8e10: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8e20: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8e30: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8e40: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8e50: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8e60: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
8e70: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8e80: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
8e90: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
8ea0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
8eb0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8ec0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
8ed0: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
8ee0: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
8ef0: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
8f00: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8f10: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8f20: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8f30: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8f40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8f50: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8f60: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8f70: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8f80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8f90: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8fa0: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8fb0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8fc0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8fd0: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8fe0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8ff0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
9000: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
9010: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
9020: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
9030: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
9040: 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  Opcodes.** KEYWO
9050: 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72  RDS: {file contr
9060: 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c  ol opcodes} {fil
9070: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
9080: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
9090: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
90a0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
90b0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
90c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
90d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
90e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
90f0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
9100: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9110: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
9120: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
9130: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9140: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a  L_LOCKSTATE]].**
9150: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9160: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
9170: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
9180: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
9190: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
91a0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
91b0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
91c0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
91d0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
91e0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
91f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
9200: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
9210: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
9220: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
9230: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
9240: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
9250: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
9260: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
9270: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
9280: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
9290: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
92a0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
92b0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
92c0: 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20  ing and is only 
92d0: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74  available when t
92e0: 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  he SQLITE_TEST.*
92f0: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
9300: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
9310: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9320: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
9330: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
9340: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
9350: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
9360: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
9370: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
9380: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
9390: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
93a0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
93b0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
93c0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
93d0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
93e0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
93f0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
9400: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
9410: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
9420: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
9430: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
9440: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
9450: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
9460: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
9470: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
9480: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
9490: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
94a0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
94b0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
94c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
94d0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
94e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
94f0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9500: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9510: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9520: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9530: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9540: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9550: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
9560: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
9570: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
9580: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
9590: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
95a0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
95b0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
95c0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
95d0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
95e0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
95f0: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9600: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9610: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9620: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9630: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9640: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9650: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
9660: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
9670: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
9680: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
9690: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
96a0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
96b0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
96c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
96d0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
96e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
96f0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9700: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9710: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9720: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9730: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9740: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9750: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9760: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9770: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9780: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
9790: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
97a0: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ER]..**.** <li>[
97b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
97c0: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a  URNAL_POINTER]].
97d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
97e0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
97f0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9800: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9810: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9820: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9830: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9840: 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75  ted with the jou
9850: 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65  rnal file (eithe
9860: 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61  r.** the [rollba
9870: 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74  ck journal] or t
9880: 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20  he [write-ahead 
9890: 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74  log]) for a part
98a0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
98b0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
98c0: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
98d0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
98e0: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
98f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9900: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9910: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9920: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9930: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9940: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9950: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
9960: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
9970: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
9980: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
9990: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
99a0: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
99b0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
99c0: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
99d0: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
99e0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
99f0: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9a00: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9a10: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9a20: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9a30: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9a40: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9a50: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
9a60: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9a70: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
9a80: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
9a90: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
9aa0: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
9ab0: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
9ac0: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
9ad0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9ae0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9af0: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9b00: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9b10: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9b20: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9b30: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
9b40: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
9b50: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
9b60: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
9b70: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
9b80: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
9b90: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
9ba0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
9bb0: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
9bc0: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
9bd0: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
9be0: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9bf0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9c00: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
9c10: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9c20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9c30: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9c40: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9c50: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
9c60: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
9c70: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
9c80: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
9c90: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
9ca0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
9cb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9cc0: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
9cd0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9ce0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9cf0: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
9d00: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9d10: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
9d20: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
9d30: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
9d40: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
9d50: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
9d60: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
9d70: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
9d80: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
9d90: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
9da0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9db0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
9dc0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9dd0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9de0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
9df0: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
9e00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9e10: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9e20: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9e30: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
9e40: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
9e50: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9e60: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9e70: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9e80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9e90: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9ea0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
9eb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9ec0: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9ed0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9ee0: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9ef0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9f00: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9f10: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9f20: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9f30: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9f40: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9f50: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
9f60: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
9f70: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
9f80: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
9f90: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9fa0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
9fb0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9fc0: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9fd0: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9fe0: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9ff0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
a000: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
a010: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
a020: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
a030: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
a040: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
a050: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
a060: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
a070: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
a080: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
a090: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
a0a0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
a0b0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
a0c0: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
a0d0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
a0e0: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
a0f0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
a100: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
a110: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
a120: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
a130: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
a140: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
a150: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
a160: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
a170: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
a180: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
a190: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
a1a0: 73 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  s the new retry 
a1b0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
a1c0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
a1d0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
a1e0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
a1f0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
a200: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
a210: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
a220: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
a230: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
a240: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
a250: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
a260: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
a270: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
a280: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
a290: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
a2a0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
a2b0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
a2c0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
a2d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a2e0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a2f0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
a300: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a310: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
a320: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a330: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a340: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
a350: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
a360: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
a370: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
a380: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
a390: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
a3a0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
a3b0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
a3c0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
a3d0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
a3e0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
a3f0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
a400: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
a410: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
a420: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
a430: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
a440: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
a450: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
a460: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
a470: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
a480: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
a490: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
a4a0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
a4b0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
a4c0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
a4d0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
a4e0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
a4f0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
a500: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
a510: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
a520: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
a530: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
a540: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
a550: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
a560: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
a570: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
a580: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a590: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a5a0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a5b0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a5c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a5d0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a5e0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a5f0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
a600: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
a610: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
a620: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
a630: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a640: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a650: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a660: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a670: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a680: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a690: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a6a0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a6b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a6c0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a6d0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a6e0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a6f0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a700: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a710: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a720: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a730: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a740: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a750: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a760: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a770: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a780: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a790: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a7a0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a7b0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a7c0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a7d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a7e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a7f0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a800: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a810: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a820: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a830: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a840: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a850: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a860: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a870: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a880: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a890: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a8a0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a8b0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a8c0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a8d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a8e0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a8f0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a910: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a920: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a930: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a940: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a950: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a960: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a970: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a980: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a990: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a9a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a9b0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a9c0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a9d0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a9e0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a9f0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
aa00: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
aa10: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aa20: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
aa30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa40: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
aa50: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
aa60: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
aa70: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
aa80: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
aa90: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
aaa0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
aab0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
aac0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
aad0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
aae0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
aaf0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
ab00: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
ab10: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
ab20: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
ab30: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
ab40: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
ab50: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
ab60: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
ab70: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
ab80: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
ab90: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
aba0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
abb0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
abc0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
abd0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
abe0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
abf0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
ac00: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
ac10: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
ac20: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
ac30: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
ac40: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
ac50: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
ac60: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
ac70: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
ac80: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
ac90: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
aca0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
acb0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
acc0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
acd0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
ace0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
acf0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
ad00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ad10: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
ad20: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
ad30: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
ad40: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
ad50: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
ad60: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
ad70: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
ad80: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
ad90: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
ada0: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
adb0: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
adc0: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
add0: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
ade0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
adf0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
ae00: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
ae10: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
ae20: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
ae30: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
ae40: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
ae50: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
ae60: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
ae70: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
ae80: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ae90: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
aea0: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
aeb0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
aec0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
aed0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aee0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
aef0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
af00: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
af10: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
af20: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
af30: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
af40: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
af50: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
af60: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
af70: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
af80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af90: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
afa0: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
afb0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
afc0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
afd0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
afe0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
aff0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
b000: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
b010: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
b020: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
b030: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
b040: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
b050: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
b060: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
b070: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
b080: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
b090: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b0a0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b0b0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
b0c0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
b0d0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
b0e0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
b0f0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
b100: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
b110: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
b120: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
b130: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
b140: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
b150: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
b160: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
b170: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
b180: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
b190: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
b1a0: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
b1b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b1c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b1d0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
b1e0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
b1f0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
b200: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
b210: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
b220: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b230: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b240: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b250: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
b260: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
b270: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
b280: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
b290: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
b2a0: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
b2b0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
b2c0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
b2d0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
b2e0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
b2f0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
b300: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
b310: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
b320: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
b330: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
b340: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
b350: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b360: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b370: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
b380: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
b390: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
b3a0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
b3b0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
b3c0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
b3d0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
b3e0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
b3f0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
b400: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
b410: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
b420: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
b430: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
b440: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b450: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
b460: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
b470: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
b480: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
b490: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
b4a0: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
b4b0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
b4c0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
b4d0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
b4e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b4f0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
b500: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
b510: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b520: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
b530: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
b540: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
b550: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
b560: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
b570: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
b580: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
b590: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
b5a0: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
b5b0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
b5c0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
b5d0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
b5e0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
b5f0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
b600: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
b610: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
b620: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
b630: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
b640: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
b650: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
b660: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
b670: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
b680: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
b690: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
b6a0: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
b6b0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
b6c0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b6d0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
b6e0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
b6f0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
b700: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b710: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b720: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b730: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b740: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b750: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b760: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b770: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b780: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b790: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b7a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b7b0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b7c0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b7d0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b7e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b7f0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b800: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b810: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b820: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b830: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b840: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b850: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b860: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b870: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b880: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b890: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b8a0: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b8b0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b8c0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b8d0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b8e0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b8f0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b900: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b910: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b920: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b930: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b940: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b950: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b960: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b970: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b980: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b9a0: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b9b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b9c0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b9d0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b9e0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b9f0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
ba00: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
ba10: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
ba20: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
ba30: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
ba40: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
ba50: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
ba60: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
ba70: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
ba80: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
ba90: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
baa0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
bab0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
bac0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
bad0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
bae0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
baf0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
bb00: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
bb10: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
bb20: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
bb30: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
bb40: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
bb50: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
bb60: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
bb70: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
bb80: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
bb90: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
bba0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
bbb0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
bbc0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
bbd0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
bbe0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
bbf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
bc00: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
bc10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
bc20: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
bc30: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
bc40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
bc50: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
bc60: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
bc70: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
bc80: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
bc90: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
bca0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
bcb0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
bcc0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
bcd0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
bce0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
bcf0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
bd00: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
bd10: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
bd20: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
bd30: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
bd40: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
bd50: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
bd60: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
bd70: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
bd80: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
bd90: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
bda0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bdb0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
bdc0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bdd0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
bde0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
bdf0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
be00: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
be10: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
be20: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
be30: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
be40: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
be50: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
be60: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
be70: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
be80: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
be90: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
bea0: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
beb0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
bec0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bed0: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
bee0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bef0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
bf00: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
bf10: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
bf20: 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75   obtain the.** u
bf30: 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65  nderlying native
bf40: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73   file handle ass
bf50: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 66  ociated with a f
bf60: 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69  ile handle.  Thi
bf70: 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f  s file.** contro
bf80: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
bf90: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70   argument as a p
bfa0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69  ointer to a nati
bfb0: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
bfc0: 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65  nd.** writes the
bfd0: 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65   resulting value
bfe0: 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c   there..**.** <l
bff0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c000: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c010: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c020: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c030: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
c040: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
c050: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
c060: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
c070: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
c080: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
c090: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
c0a0: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
c0b0: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
c0c0: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
c0d0: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
c0e0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
c0f0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
c100: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
c110: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
c120: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
c130: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
c140: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c150: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
c160: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c170: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
c180: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
c190: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
c1a0: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
c1b0: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
c1c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
c1d0: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
c1e0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
c1f0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
c200: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
c210: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
c220: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
c230: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
c240: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
c250: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
c260: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
c270: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
c280: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
c290: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
c2a0: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
c2b0: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
c2c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c2d0: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
c2e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
c2f0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
c300: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
c310: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
c320: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
c330: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
c340: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
c350: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
c360: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c370: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
c380: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c390: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
c3a0: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
c3b0: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
c3c0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
c3d0: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
c3e0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
c3f0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
c400: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
c410: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
c420: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
c430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
c440: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
c450: 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c  ].** If the [SQL
c460: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c470: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
c480: 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53 51 4c  code returns SQL
c490: 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20  ITE_OK, then.** 
c4a0: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
c4b0: 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20 69 6e  tor is placed in
c4c0: 20 22 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f   "batch write mo
c4d0: 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20 6d 65  de", which.** me
c4e0: 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ans all subseque
c4f0: 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  nt write operati
c500: 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65 66 65  ons will be defe
c510: 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a  rred and done.**
c520: 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74 20 74   atomically at t
c530: 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54 45 5f  he next [SQLITE_
c540: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c550: 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53 79 73  MIC_WRITE].  Sys
c560: 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  tems.** that do 
c570: 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61 74 63  not support batc
c580: 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65 73 20  h atomic writes 
c590: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
c5a0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20  TE_NOTFOUND..** 
c5b0: 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 75 63  ^Following a suc
c5c0: 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45 5f 46  cessful SQLITE_F
c5d0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
c5e0: 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72 69 6f  C_WRITE and prio
c5f0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c 6f 73  r to.** the clos
c600: 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  ing [SQLITE_FCNT
c610: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
c620: 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51  WRITE] or.** [SQ
c630: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
c640: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
c650: 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6d  ], SQLite will m
c660: 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20 69 6e  ake.** no VFS in
c670: 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20 6f 6e  terface calls on
c680: 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c 69 74   the same [sqlit
c690: 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20 64 65  e3_file] file de
c6a0: 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78 63 65  scriptor.** exce
c6b0: 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74 6f 20  pt for calls to 
c6c0: 74 68 65 20 78 57 72 69 74 65 20 6d 65 74 68 6f  the xWrite metho
c6d0: 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c 65 43  d and the xFileC
c6e0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
c6f0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 46 43   with [SQLITE_FC
c700: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a  NTL_SIZE_HINT]..
c710: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c720: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c730: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a  ATOMIC_WRITE]].*
c740: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c750: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c760: 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  C_WRITE] opcode 
c770: 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65  causes all write
c780: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73  .** operations s
c790: 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75  ince the previou
c7a0: 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  s successful cal
c7b0: 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  l to .** [SQLITE
c7c0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c7d0: 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65  MIC_WRITE] to be
c7e0: 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f 6d 69   performed atomi
c7f0: 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 20 66  cally..** This f
c800: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
c810: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
c820: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
c830: 68 65 20 77 72 69 74 65 73 20 77 65 72 65 0a 2a  he writes were.*
c840: 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65 64 20  * all performed 
c850: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64  successfully and
c860: 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d 6d 69   have been commi
c870: 74 74 65 64 20 74 6f 20 70 65 72 73 69 73 74 65  tted to persiste
c880: 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e  nt storage..** ^
c890: 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
c8a0: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
c8b0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c 20 74  is successful, t
c8c0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c8d0: 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20 66 69   takes.** the fi
c8e0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75  le descriptor ou
c8f0: 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65  t of batch write
c900: 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20 61 6c   mode so that al
c910: 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
c920: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
c930: 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74   are independent
c940: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
c950: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53  l never invoke S
c960: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c970: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  IT_ATOMIC_WRITE 
c980: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69  without.** a pri
c990: 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
c9a0: 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43  ll to [SQLITE_FC
c9b0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
c9c0: 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  _WRITE]..**.** <
c9d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c9e0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
c9f0: 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65  C_WRITE]].** The
ca00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
ca10: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
ca20: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75  RITE] opcode cau
ca30: 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a  ses all write.**
ca40: 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63   operations sinc
ca50: 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  e the previous s
ca60: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
ca70: 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  o .** [SQLITE_FC
ca80: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
ca90: 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 72 6f  _WRITE] to be ro
caa0: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54  lled back..** ^T
cab0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
cac0: 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c 65 20   takes the file 
cad0: 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f  descriptor out o
cae0: 66 20 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f  f batch write mo
caf0: 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20 61 6c  de.** so that al
cb00: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69  l subsequent wri
cb10: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
cb20: 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a  e independent..*
cb30: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
cb40: 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49  ever invoke SQLI
cb50: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
cb60: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 77  K_ATOMIC_WRITE w
cb70: 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f  ithout.** a prio
cb80: 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
cb90: 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  l to [SQLITE_FCN
cba0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
cbb0: 57 52 49 54 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  WRITE]..** </ul>
cbc0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
cbd0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
cbe0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
cbf0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
cc00: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b  E_FCNTL_GET_LOCK
cc10: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
cc20: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
cc30: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
cc40: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33  ROXYFILE       3
cc50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cc60: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
cc70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
cc80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cc90: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
cca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
ccb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ccc0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
ccd0: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
cce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ccf0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
cd00: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
cd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cd20: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
cd30: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
cd40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cd50: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
cd60: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
cd70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cd80: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
cd90: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
cda0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
cdb0: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
cdc0: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
cdd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
cde0: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
cdf0: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
ce00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
ce10: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
ce20: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
ce30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ce40: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
ce50: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
ce70: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
ce80: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
ce90: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
cea0: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
ceb0: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
cec0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
ced0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
cee0: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  18.#define SQLIT
cef0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20  E_FCNTL_TRACE   
cf00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
cf10: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
cf20: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
cf30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
cf40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cf50: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20  FCNTL_SYNC      
cf60: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a               21.
cf70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cf80: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
cf90: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23  ETWO        22.#
cfa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cfb0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
cfc0: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64  NDLE       23.#d
cfd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cfe0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20  TL_WAL_BLOCK    
cff0: 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65            24.#de
d000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d010: 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20  L_ZIPVFS        
d020: 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66           25.#def
d030: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d040: 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20  _RBU            
d050: 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69          26.#defi
d060: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d070: 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  VFS_POINTER     
d080: 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e         27.#defin
d090: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a  e SQLITE_FCNTL_J
d0a0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20  OURNAL_POINTER  
d0b0: 20 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65        28.#define
d0c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
d0d0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20  N32_GET_HANDLE  
d0e0: 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20       29.#define 
d0f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42  SQLITE_FCNTL_PDB
d100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d110: 20 20 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53      30.#define S
d120: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
d130: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20  N_ATOMIC_WRITE  
d140: 20 20 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51     31.#define SQ
d150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
d160: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20  T_ATOMIC_WRITE  
d170: 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    32.#define SQL
d180: 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41  ITE_FCNTL_ROLLBA
d190: 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  CK_ATOMIC_WRITE 
d1a0: 20 33 33 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74   33../* deprecat
d1b0: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66  ed names */.#def
d1c0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
d1d0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
d1e0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47    SQLITE_FCNTL_G
d1f0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
d200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d210: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
d220: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
d230: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
d240: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
d250: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
d260: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49              SQLI
d270: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
d280: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  RNO.../*.** CAPI
d290: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
d2a0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
d2b0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
d2c0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
d2d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
d2e0: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
d2f0: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
d300: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
d310: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
d320: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
d330: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
d340: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
d350: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
d360: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
d370: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
d380: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
d390: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
d3a0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
d3b0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
d3c0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
d3d0: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
d3e0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
d3f0: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
d400: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
d410: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
d420: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54  able Extension T
d430: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  hunk.**.** A poi
d440: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71  nter to the opaq
d450: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ue sqlite3_api_r
d460: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72  outines structur
d470: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a  e is passed as.*
d480: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
d490: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70  meter to entry p
d4a0: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62  oints of [loadab
d4b0: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20  le extensions]. 
d4c0: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75   This.** structu
d4d0: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64  re must be typed
d4e0: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  efed in order to
d4f0: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d   work around com
d500: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a  piler warnings.*
d510: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f  * on some platfo
d520: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  rms..*/.typedef 
d530: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
d540: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69  pi_routines sqli
d550: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
d560: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d570: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
d580: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
d590: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d5a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
d5b0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
d5c0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
d5d0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
d5e0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
d5f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
d600: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
d610: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
d620: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
d630: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
d640: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
d650: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
d660: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
d670: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
d680: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
d690: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
d6a0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
d6b0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
d6c0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
d6d0: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
d6e0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
d6f0: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
d700: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
d710: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
d720: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
d730: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
d740: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
d750: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
d760: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
d770: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
d780: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
d790: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
d7a0: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
d7b0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
d7c0: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
d7d0: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
d7e0: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
d7f0: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
d800: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
d810: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
d820: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
d830: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
d840: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
d850: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
d860: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
d870: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
d880: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
d890: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
d8a0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
d8b0: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
d8c0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
d8d0: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
d8e0: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
d8f0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
d900: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
d910: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
d920: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
d930: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
d940: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
d950: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
d960: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
d970: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
d980: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
d990: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
d9a0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
d9b0: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
d9c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
d9d0: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
d9e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
d9f0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
da00: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
da10: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
da20: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
da30: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
da40: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
da50: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
da60: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
da70: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
da80: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
da90: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
daa0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
dab0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
dac0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
dad0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
dae0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
daf0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
db00: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
db10: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
db20: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
db30: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
db40: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
db50: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
db60: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
db70: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
db80: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
db90: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
dba0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
dbb0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
dbc0: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
dbd0: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
dbe0: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
dbf0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
dc00: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
dc10: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
dc20: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
dc30: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
dc40: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
dc50: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
dc60: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
dc70: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
dc80: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
dc90: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
dca0: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
dcb0: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
dcc0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
dcd0: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
dce0: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
dcf0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
dd00: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
dd10: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
dd20: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
dd30: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
dd40: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
dd50: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
dd60: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
dd70: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
dd80: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
dd90: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
dda0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ddb0: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ddc0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ddd0: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
dde0: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
ddf0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
de00: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
de10: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
de20: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
de30: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
de40: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
de50: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
de60: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
de70: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
de80: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
de90: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
dea0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
deb0: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
dec0: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
ded0: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
dee0: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
def0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
df00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
df10: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
df20: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
df30: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
df40: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
df50: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
df60: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
df70: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
df80: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
df90: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
dfa0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
dfb0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
dfc0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
dfd0: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
dfe0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
dff0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
e000: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
e010: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
e020: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
e030: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
e040: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
e050: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
e060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
e070: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
e080: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
e090: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
e0a0: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
e0b0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
e0c0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
e0d0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
e0e0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
e0f0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
e100: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
e110: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
e120: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e130: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
e140: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e150: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
e160: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e170: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
e180: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e190: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
e1a0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e1b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
e1c0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
e1d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
e1e0: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
e1f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e200: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
e210: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e220: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
e230: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
e240: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
e250: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
e260: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
e270: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
e280: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
e290: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
e2a0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
e2b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
e2c0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
e2d0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
e2e0: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
e2f0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
e300: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
e310: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
e320: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
e330: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
e340: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
e350: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
e360: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
e370: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
e380: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
e390: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
e3a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e3b0: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
e3c0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
e3d0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
e3e0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
e3f0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
e400: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
e410: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
e420: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
e430: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
e440: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
e450: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
e460: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
e470: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
e480: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
e490: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
e4a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
e4b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
e4c0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
e4d0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
e4e0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
e4f0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
e500: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
e510: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
e520: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
e530: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
e540: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
e550: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
e560: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e570: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
e580: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
e590: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
e5a0: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
e5b0: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
e5c0: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
e5d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
e5e0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
e5f0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
e600: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
e610: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
e620: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
e630: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
e640: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
e650: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
e660: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
e670: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
e680: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
e690: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
e6a0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
e6b0: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
e6c0: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
e6d0: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
e6e0: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
e6f0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
e700: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
e710: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
e720: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
e730: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
e740: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
e750: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
e760: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
e770: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
e780: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
e790: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
e7a0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
e7b0: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
e7c0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
e7d0: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
e7e0: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
e7f0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
e800: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
e810: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
e820: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
e830: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
e840: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
e850: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
e860: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
e870: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
e880: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
e890: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
e8a0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
e8b0: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
e8c0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
e8d0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
e8e0: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
e8f0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
e900: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
e910: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
e920: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
e930: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
e940: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
e950: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
e960: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
e970: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
e980: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
e990: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
e9a0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
e9b0: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
e9c0: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
e9d0: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
e9e0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
e9f0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
ea00: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
ea10: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
ea20: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
ea30: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
ea40: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
ea50: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
ea60: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
ea70: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
ea80: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
ea90: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
eaa0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
eab0: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
eac0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ead0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
eae0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
eaf0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
eb00: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
eb10: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
eb20: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
eb30: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
eb40: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
eb50: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
eb60: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
eb70: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
eb80: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
eb90: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
eba0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
ebb0: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
ebc0: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
ebd0: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
ebe0: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
ebf0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
ec00: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
ec10: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
ec20: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
ec30: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
ec40: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
ec50: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
ec60: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
ec70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
ec80: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
ec90: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
eca0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
ecb0: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
ecc0: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
ecd0: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
ece0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
ecf0: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
ed00: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
ed10: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
ed20: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
ed30: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
ed40: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
ed50: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
ed60: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
ed70: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
ed80: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
ed90: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
eda0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
edb0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
edc0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
edd0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
ede0: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
edf0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
ee00: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
ee10: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
ee20: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
ee30: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
ee40: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
ee50: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
ee60: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
ee70: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
ee80: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
ee90: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
eea0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
eeb0: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
eec0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
eed0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
eee0: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
eef0: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
ef00: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
ef10: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
ef20: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
ef30: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
ef40: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
ef50: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
ef60: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
ef70: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
ef80: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
ef90: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
efa0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
efb0: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
efc0: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
efd0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
efe0: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
eff0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
f000: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
f010: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
f020: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
f030: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
f040: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
f050: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
f060: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
f070: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
f080: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
f090: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
f0a0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
f0b0: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
f0c0: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
f0d0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
f0e0: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
f0f0: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
f100: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
f110: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
f120: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
f130: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
f140: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
f150: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
f160: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
f170: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
f180: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
f190: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
f1a0: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
f1b0: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
f1c0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
f1d0: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
f1e0: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
f1f0: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
f200: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
f210: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
f220: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
f230: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
f240: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
f250: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
f260: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
f270: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
f280: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
f290: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
f2a0: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
f2b0: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
f2c0: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
f2d0: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
f2e0: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
f2f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
f300: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
f310: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
f320: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
f330: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
f340: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
f350: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
f360: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
f370: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
f380: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
f390: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
f3a0: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
f3b0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
f3c0: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
f3d0: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
f3e0: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
f3f0: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
f400: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
f410: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
f420: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
f430: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
f440: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
f450: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
f460: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
f470: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
f480: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
f490: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
f4a0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
f4b0: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
f4c0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
f4d0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
f4e0: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
f4f0: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
f500: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
f510: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
f520: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
f530: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
f540: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
f550: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
f560: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
f570: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f580: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
f590: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
f5a0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
f5b0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
f5c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
f5d0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
f5e0: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
f5f0: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
f600: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
f610: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f620: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
f630: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
f640: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
f650: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
f660: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
f670: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f680: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f690: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
f6a0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
f6b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f6c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f6d0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
f6e0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
f6f0: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
f700: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f710: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f720: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
f730: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
f740: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
f750: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f760: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
f770: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
f780: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
f790: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
f7a0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
f7b0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
f7c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
f7d0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
f7e0: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
f7f0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
f800: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
f810: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
f820: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
f830: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
f840: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
f850: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
f860: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
f870: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
f880: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
f890: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
f8a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
f8b0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
f8c0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
f8d0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
f8e0: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
f8f0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
f900: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
f910: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
f920: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
f930: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
f940: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
f950: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
f960: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
f970: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
f980: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
f990: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
f9a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
f9b0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
f9c0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
f9d0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
f9e0: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
f9f0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
fa00: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
fa10: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
fa20: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
fa30: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
fa40: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
fa50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fa60: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
fa70: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
fa80: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
fa90: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
faa0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
fab0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
fac0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
fad0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
fae0: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
faf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
fb00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
fb10: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
fb20: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
fb30: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
fb40: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
fb50: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
fb60: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
fb70: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
fb80: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
fb90: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
fba0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
fbb0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
fbc0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
fbd0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
fbe0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fbf0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
fc00: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
fc10: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
fc20: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
fc30: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
fc40: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
fc50: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
fc60: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
fc70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
fc80: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
fc90: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
fca0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
fcb0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
fcc0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
fcd0: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
fce0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
fcf0: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
fd00: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
fd10: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
fd20: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
fd30: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
fd40: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
fd50: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
fd60: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
fd70: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
fd80: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
fd90: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
fda0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
fdb0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
fdc0: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
fdd0: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
fde0: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
fdf0: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
fe00: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
fe10: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
fe20: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
fe30: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
fe40: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
fe50: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
fe60: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
fe70: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
fe80: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
fe90: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
fea0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
feb0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
fec0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
fed0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
fee0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
fef0: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
ff00: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ff10: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
ff20: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
ff30: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
ff40: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
ff50: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
ff60: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
ff70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ff80: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
ff90: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
ffa0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
ffb0: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
ffc0: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
ffd0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
ffe0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
fff0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
10000 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
10010 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
10020 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
10030 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
10040 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
10050 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
10060 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
10070 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
10080 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
10090 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
100a0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
100b0 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
100c0 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
100d0 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
100e0 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
100f0 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
10100 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
10110 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
10120 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
10130 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10140 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
10150 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
10160 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10170 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10180 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
10190 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
101a0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
101b0 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
101c0 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
101d0 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
101e0 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
101f0 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
10200 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
10210 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
10220 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
10230 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
10240 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
10250 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
10260 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
10270 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
10280 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
10290 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
102a0 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
102b0 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
102c0 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
102d0 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
102e0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
102f0 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
10300 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
10310 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
10320 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
10330 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
10340 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
10350 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10360 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
10370 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10380 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
10390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
103a0 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
103b0 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
103c0 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
103d0 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
103e0 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
103f0 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
10400 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
10410 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
10420 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
10430 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
10440 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
10450 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
10460 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
10470 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
10480 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
10490 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
104a0 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
104b0 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
104c0 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
104d0 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
104e0 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
104f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10500 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
10510 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
10520 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
10530 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
10540 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
10550 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
10560 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
10570 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
10580 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
10590 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
105a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
105b0 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
105c0 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
105d0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
105e0 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
105f0 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
10600 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
10610 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
10620 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
10630 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
10640 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
10650 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
10660 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
10670 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
10680 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
10690 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
106a0 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
106b0 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
106c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
106d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
106e0 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
106f0 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
10700 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
10710 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
10720 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10730 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
10740 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
10750 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
10760 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
10770 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
10780 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
10790 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
107a0 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
107b0 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
107c0 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
107d0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
107e0 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
107f0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10800 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
10810 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
10820 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
10830 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
10840 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
10850 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
10860 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10870 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
10880 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
10890 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
108a0 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
108b0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
108c0 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
108d0 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
108e0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
108f0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
10900 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
10910 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10920 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
10930 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
10940 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
10950 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
10960 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
10970 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
10980 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
10990 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
109a0 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
109b0 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
109c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
109d0 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
109e0 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
109f0 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
10a00 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
10a10 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
10a20 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
10a30 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
10a40 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
10a50 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
10a60 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
10a70 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
10a80 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
10a90 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
10aa0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
10ab0 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
10ac0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
10ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10ae0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10af0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10b00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
10b10 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
10b20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
10b30 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10b40 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
10b50 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
10b60 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
10b70 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
10b80 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
10b90 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
10ba0 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
10bb0 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
10bc0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
10bd0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
10be0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
10bf0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
10c00 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
10c10 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
10c20 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
10c30 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
10c40 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
10c50 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
10c60 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
10c70 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
10c80 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10c90 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
10ca0 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
10cb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
10cc0 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
10cd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
10ce0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10cf0 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
10d00 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
10d10 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
10d20 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
10d30 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
10d40 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
10d50 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
10d60 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
10d70 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10d80 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
10d90 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
10da0 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
10db0 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
10dc0 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
10dd0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
10de0 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
10df0 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
10e00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
10e10 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
10e20 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
10e30 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
10e40 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
10e50 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10e60 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
10e70 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
10e80 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
10e90 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
10ea0 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
10eb0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
10ec0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
10ed0 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
10ee0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10ef0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
10f00 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
10f10 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
10f20 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
10f30 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
10f40 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
10f50 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
10f60 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10f70 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
10f80 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
10f90 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
10fa0 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
10fb0 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
10fc0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
10fd0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
10fe0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10ff0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
11000 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
11010 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
11020 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
11030 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11040 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
11050 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
11060 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
11070 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
11080 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
11090 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
110a0 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
110b0 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
110c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
110d0 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
110e0 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
110f0 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
11100 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
11110 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
11120 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
11130 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
11140 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
11150 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
11160 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
11170 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
11180 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
11190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
111a0 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
111b0 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
111c0 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
111d0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
111e0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
111f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11200 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
11210 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
11220 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
11230 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11240 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11250 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
11260 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
11270 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
11280 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11290 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
112a0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
112b0 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
112c0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
112d0 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
112e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
112f0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
11300 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
11310 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
11320 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11330 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
11340 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
11350 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
11360 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
11370 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
11380 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
11390 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
113a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
113b0 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
113c0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
113d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
113e0 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
113f0 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
11400 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
11410 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
11420 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
11430 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
11440 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
11450 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11460 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
11470 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
11480 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
11490 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
114a0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
114b0 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
114c0 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
114d0 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
114e0 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
114f0 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
11500 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11510 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
11520 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
11530 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
11540 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
11550 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11560 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
11570 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
11580 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11590 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
115a0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
115b0 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
115c0 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
115d0 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
115e0 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
115f0 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
11600 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
11610 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
11620 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
11630 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
11640 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
11650 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
11660 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
11670 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
11680 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
11690 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
116a0 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
116b0 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
116c0 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
116d0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
116e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
116f0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
11700 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
11710 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
11720 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
11730 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
11740 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
11750 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
11760 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
11770 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
11780 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
11790 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
117a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
117b0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
117c0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
117d0 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
117e0 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
117f0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
11800 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11810 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
11820 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
11830 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
11840 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
11850 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
11860 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
11870 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
11880 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
11890 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
118a0 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
118b0 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
118c0 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
118d0 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
118e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
118f0 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
11900 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
11910 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
11920 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
11930 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
11940 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
11950 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
11960 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
11970 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
11980 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
11990 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
119a0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
119b0 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
119c0 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
119d0 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
119e0 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
119f0 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
11a00 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
11a10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11a20 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
11a30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
11a40 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
11a50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11a60 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
11a70 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
11a80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
11a90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
11aa0 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
11ab0 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
11ac0 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
11ad0 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
11ae0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
11af0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
11b00 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
11b10 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11b20 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
11b30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11b40 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
11b50 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
11b60 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
11b70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11b80 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
11b90 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
11ba0 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
11bb0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11bc0 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
11bd0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
11be0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
11bf0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
11c00 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
11c10 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
11c20 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
11c30 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
11c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11c50 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
11c60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11c70 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
11c80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11c90 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11ca0 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
11cb0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
11cc0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11cd0 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
11ce0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
11cf0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
11d00 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
11d10 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
11d20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11d30 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
11d40 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
11d50 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11d60 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
11d70 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
11d80 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
11d90 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
11da0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11db0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
11dc0 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
11dd0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
11de0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
11df0 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
11e00 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
11e10 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
11e20 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
11e30 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
11e40 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
11e50 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
11e60 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11e70 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
11e80 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
11e90 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
11ea0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
11eb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11ec0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
11ed0 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
11ee0 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
11ef0 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
11f00 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
11f10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
11f20 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
11f30 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
11f40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
11f50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11f60 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
11f70 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
11f80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11f90 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
11fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
11fb0 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
11fc0 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
11fd0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11fe0 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
11ff0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
12000 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
12010 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12020 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
12030 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
12040 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
12050 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
12060 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
12070 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
12080 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
12090 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
120a0 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
120b0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
120c0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
120d0 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
120e0 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
120f0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
12100 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
12110 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
12120 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
12130 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
12140 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
12150 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
12160 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
12170 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
12180 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
12190 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
121a0 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
121b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
121c0 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
121d0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
121e0 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
121f0 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
12200 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
12210 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
12220 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
12230 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
12240 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
12250 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
12260 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
12270 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
12280 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
12290 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
122a0 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
122b0 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
122c0 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
122d0 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
122e0 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
122f0 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
12300 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
12310 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
12320 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
12330 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12340 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
12350 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
12360 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
12370 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
12380 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
12390 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
123a0 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
123b0 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
123c0 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
123d0 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
123e0 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
123f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12400 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
12410 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
12420 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
12430 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
12440 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
12450 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
12460 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
12470 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
12480 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
12490 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
124a0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
124b0 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
124c0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
124d0 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
124e0 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
124f0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
12500 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
12510 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
12520 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
12530 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12540 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
12550 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
12560 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
12570 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
12580 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
12590 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
125a0 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
125b0 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
125c0 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
125d0 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
125e0 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
125f0 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
12600 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
12610 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
12620 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
12630 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
12640 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
12650 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
12660 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12670 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
12680 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
12690 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
126a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
126b0 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
126c0 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
126d0 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
126e0 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
126f0 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
12700 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
12710 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
12720 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
12730 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
12740 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
12750 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
12760 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
12770 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
12780 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
12790 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
127a0 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
127b0 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
127c0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
127d0 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
127e0 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
127f0 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
12800 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
12810 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
12820 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
12830 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
12840 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
12850 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
12860 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
12870 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
12880 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
12890 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
128a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
128b0 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
128c0 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
128d0 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
128e0 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
128f0 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
12900 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
12910 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
12920 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
12930 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
12940 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
12950 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
12960 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12970 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
12980 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
12990 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
129a0 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
129b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
129c0 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
129d0 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
129e0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
129f0 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
12a00 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
12a10 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
12a20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
12a30 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
12a40 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
12a50 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
12a60 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
12a70 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
12a80 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
12a90 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
12aa0 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
12ab0 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
12ac0 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
12ad0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
12ae0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12af0 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
12b00 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
12b10 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12b20 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
12b30 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
12b40 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
12b50 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
12b60 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
12b70 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
12b80 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
12b90 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
12ba0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
12bb0 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
12bc0 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
12bd0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
12be0 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
12bf0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
12c00 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
12c10 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
12c20 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
12c30 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
12c40 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
12c50 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
12c60 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
12c70 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
12c80 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
12c90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
12ca0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
12cb0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
12cc0 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
12cd0 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
12ce0 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
12cf0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
12d00 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
12d10 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
12d20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
12d30 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
12d40 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
12d50 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
12d60 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
12d70 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
12d80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
12d90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12da0 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
12db0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
12dc0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
12dd0 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
12de0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
12df0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
12e00 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
12e10 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
12e20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
12e30 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
12e40 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
12e50 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
12e60 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
12e70 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
12e80 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
12e90 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12ea0 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
12eb0 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
12ec0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
12ed0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
12ee0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
12ef0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12f00 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
12f10 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
12f20 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
12f30 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12f40 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
12f50 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
12f60 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
12f70 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
12f80 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
12f90 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
12fa0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
12fb0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
12fc0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
12fd0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12fe0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
12ff0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
13000 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
13010 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
13020 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
13030 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
13040 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13050 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13060 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
13070 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
13080 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
13090 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
130a0 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
130b0 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
130c0 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
130d0 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
130e0 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
130f0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13100 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13110 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13120 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13130 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13140 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13150 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
13160 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
13170 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
13180 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
13190 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
131a0 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
131b0 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
131c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
131d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
131e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
131f0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13200 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13210 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
13220 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13230 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13240 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13250 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
13260 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13270 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
13280 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
13290 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
132a0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
132b0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
132c0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
132d0 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
132e0 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
132f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
13300 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
13310 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
13320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13330 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13340 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
13350 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
13360 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
13370 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
13380 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
13390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
133a0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
133b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
133c0 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
133d0 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
133e0 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
133f0 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
13400 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
13410 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
13420 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
13430 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
13440 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
13450 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
13460 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13470 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
13480 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
13490 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
134a0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
134b0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
134c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
134d0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
134e0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
134f0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
13500 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
13510 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
13520 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
13530 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13540 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
13550 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13560 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
13570 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
13580 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
13590 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
135a0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
135b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
135c0 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
135d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
135e0 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
135f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
13600 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
13610 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
13620 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
13630 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
13640 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
13650 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
13660 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
13670 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
13680 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
13690 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
136a0 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
136b0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
136c0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
136d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
136e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
136f0 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
13700 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
13710 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
13720 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13730 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13740 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
13750 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
13760 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
13770 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
13780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13790 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
137a0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
137b0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
137c0 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
137d0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
137e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
137f0 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
13800 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
13810 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
13820 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
13830 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
13840 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
13850 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13860 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13870 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13880 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13890 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
138a0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
138b0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
138c0 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
138d0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
138e0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
138f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13900 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
13910 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13920 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
13930 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
13940 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
13950 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13960 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13970 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13980 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
13990 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
139a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
139b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
139c0 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
139d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
139e0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
139f0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
13a00 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13a10 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13a20 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13a30 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
13a40 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
13a50 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
13a60 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
13a70 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13a80 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
13a90 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
13aa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13ab0 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
13ac0 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
13ad0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
13ae0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
13af0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
13b00 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13b10 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
13b20 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
13b30 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
13b40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
13b50 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
13b60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13b70 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
13b80 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13b90 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
13ba0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13bb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13bc0 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
13bd0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13be0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
13bf0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13c00 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
13c10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
13c20 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13c30 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
13c40 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
13c50 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
13c60 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
13c70 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
13c80 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
13c90 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
13ca0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
13cb0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
13cc0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
13cd0 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
13ce0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
13cf0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
13d00 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
13d10 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
13d20 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
13d30 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
13d40 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
13d50 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
13d60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13d70 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20  _SMALL_MALLOC]] 
13d80 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13d90 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f  G_SMALL_MALLOC</
13da0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13db0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13dc0 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  MALL_MALLOC opti
13dd0 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
13de0 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74  argument of.** t
13df0 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
13e00 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
13e10 6e 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65  n, which if true
13e20 20 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74   provides a hint
13e30 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68   to.** SQLite th
13e40 61 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f  at it should avo
13e50 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20  id large memory 
13e60 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70  allocations if p
13e70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69  ossible..** SQLi
13e80 74 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74  te will run fast
13e90 65 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65  er if it is free
13ea0 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d   to make large m
13eb0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13ec0 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61  s,.** but some a
13ed0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
13ee0 20 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73   prefer to run s
13ef0 6c 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67  lower in exchang
13f00 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74  e for.** guarant
13f10 65 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79  ees about memory
13f20 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74   fragmentation t
13f30 68 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65  hat are possible
13f40 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c   if large.** all
13f50 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f  ocations are avo
13f60 69 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74  ided.  This hint
13f70 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66   is normally off
13f80 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
13f90 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13fa0 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
13fb0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13fc0 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
13fd0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13fe0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13ff0 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
14000 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14010 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
14020 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
14030 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
14040 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
14050 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
14060 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
14070 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14080 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
14090 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
140a0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
140b0 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
140c0 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
140d0 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
140e0 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
140f0 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
14100 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14110 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
14120 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
14130 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
14140 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
14150 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
14160 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
14170 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14180 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
14190 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
141a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
141b0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
141c0 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
141d0 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
141e0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
141f0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
14200 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
14210 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
14220 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14230 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
14240 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
14250 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
14260 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14270 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
14280 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14290 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
142a0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
142b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
142c0 43 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20  CH option is no 
142d0 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20  longer used..** 
142e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
142f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14300 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
14310 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14320 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
14330 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14340 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
14350 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
14360 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
14370 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
14380 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
14390 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
143a0 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
143b0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
143c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
143d0 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
143e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
143f0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
14400 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14410 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
14420 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
14430 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
14440 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
14450 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
14460 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
14470 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
14480 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14490 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
144a0 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
144b0 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
144c0 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
144d0 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
144e0 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
144f0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
14500 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
14510 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
14520 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
14530 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
14540 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
14550 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
14560 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
14570 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
14580 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
14590 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
145a0 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
145b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
145c0 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
145d0 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
145e0 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
145f0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
14600 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14610 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
14620 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
14630 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
14640 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
14650 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
14660 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
14670 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
14680 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
14690 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
146a0 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
146b0 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
146c0 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
146d0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
146e0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
146f0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
14700 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
14710 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
14720 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
14730 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
14740 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
14750 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
14760 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
14770 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
14780 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
14790 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
147a0 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
147b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
147c0 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
147d0 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
147e0 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
147f0 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
14800 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
14810 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
14820 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
14830 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
14840 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
14850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14860 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
14870 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
14880 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
14890 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
148a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
148b0 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
148c0 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
148d0 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
148e0 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
148f0 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
14900 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
14910 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
14920 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
14930 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
14940 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
14950 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
14960 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
14970 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
14980 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
14990 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
149a0 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
149b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
149c0 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
149d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
149e0 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
149f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14a00 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
14a10 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14a20 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
14a30 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
14a40 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
14a50 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
14a60 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
14a70 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
14a80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14a90 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
14aa0 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
14ab0 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
14ac0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
14ad0 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
14ae0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
14af0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14b00 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
14b10 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
14b20 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
14b30 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
14b40 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
14b50 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
14b60 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
14b70 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
14b80 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
14b90 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
14ba0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
14bb0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
14bc0 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
14bd0 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
14be0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
14bf0 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
14c00 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
14c10 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
14c20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
14c30 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
14c40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
14c50 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14c60 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
14c70 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
14c80 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
14c90 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
14ca0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
14cb0 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
14cc0 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
14cd0 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
14ce0 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
14cf0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
14d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14d10 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
14d20 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
14d30 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
14d40 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
14d50 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
14d60 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
14d70 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
14d80 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
14d90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
14da0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
14db0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
14dc0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
14dd0 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
14de0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
14df0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
14e00 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
14e10 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
14e20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
14e30 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14e40 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
14e50 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
14e60 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
14e70 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
14e80 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
14e90 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
14ea0 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
14eb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14ec0 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
14ed0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14ee0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
14ef0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14f00 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
14f10 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14f20 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14f30 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
14f40 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
14f50 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14f60 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14f70 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
14f80 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
14f90 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
14fa0 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
14fb0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
14fc0 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
14fd0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
14fe0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
14ff0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
15000 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
15010 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
15020 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15030 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15040 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
15050 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
15060 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15070 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
15080 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15090 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
150a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
150b0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
150c0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
150d0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
150e0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
150f0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
15100 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
15110 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
15120 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
15130 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
15140 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
15150 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15160 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15170 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
15180 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
15190 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
151a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
151b0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
151c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
151d0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
151e0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
151f0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
15200 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15210 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
15220 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
15230 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
15240 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15250 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15260 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
15270 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
15280 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
15290 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
152a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
152b0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
152c0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
152d0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
152e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
152f0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
15300 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
15310 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
15320 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
15330 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
15340 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
15350 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
15360 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
15370 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
15380 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
15390 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
153a0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
153b0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
153c0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
153d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
153e0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
153f0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
15400 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
15410 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
15420 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
15430 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
15440 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
15450 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
15460 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
15470 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15480 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15490 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
154a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
154b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
154c0 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
154d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
154e0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
154f0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15500 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
15510 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
15520 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
15530 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
15540 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
15550 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15560 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
15570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
15580 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
15590 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
155a0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
155b0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
155c0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
155d0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
155e0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
155f0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
15600 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15610 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
15620 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
15630 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
15640 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
15650 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
15660 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15670 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
15680 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
15690 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
156a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
156b0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
156c0 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
156d0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
156e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
156f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15700 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15710 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
15720 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
15730 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15740 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15750 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
15760 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15770 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15780 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
15790 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
157a0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
157b0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
157c0 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
157d0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
157e0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
157f0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
15800 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
15810 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
15820 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15830 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
15840 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
15850 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15860 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
15870 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15880 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
15890 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
158a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
158b0 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
158c0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
158d0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
158e0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
158f0 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
15900 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
15910 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
15920 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
15930 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
15940 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15950 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
15960 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
15970 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15980 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
15990 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
159a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
159b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
159c0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
159d0 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
159e0 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
159f0 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
15a00 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
15a10 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
15a20 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
15a30 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
15a40 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
15a50 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
15a60 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
15a70 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
15a80 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
15a90 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
15aa0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
15ab0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
15ac0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
15ad0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
15ae0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
15af0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
15b00 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
15b10 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
15b20 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
15b30 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
15b40 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
15b50 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
15b60 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
15b70 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
15b80 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15b90 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
15ba0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
15bb0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
15bc0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15bd0 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
15be0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15bf0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
15c00 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
15c10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
15c20 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
15c30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
15c40 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
15c50 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
15c60 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
15c70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
15c80 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
15c90 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
15ca0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
15cb0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
15cc0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
15cd0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
15ce0 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
15cf0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15d00 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
15d10 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
15d20 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
15d30 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
15d40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15d50 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
15d60 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
15d70 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
15d80 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
15d90 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
15da0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
15db0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
15dc0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
15dd0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
15de0 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
15df0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
15e00 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
15e10 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
15e20 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
15e30 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
15e40 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
15e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15e60 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
15e70 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
15e80 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
15e90 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
15ea0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15eb0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
15ec0 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
15ed0 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
15ee0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
15ef0 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
15f00 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
15f10 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
15f20 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15f30 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
15f40 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
15f50 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
15f60 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
15f70 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
15f80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
15f90 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
15fa0 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
15fb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
15fc0 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
15fd0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
15fe0 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
15ff0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
16000 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
16010 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
16020 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
16030 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
16040 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
16050 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
16060 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
16070 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
16080 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
16090 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
160a0 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
160b0 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
160c0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
160d0 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
160e0 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
160f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
16100 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
16110 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
16120 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16130 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
16140 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
16150 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
16160 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
16170 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
16180 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
16190 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
161a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
161b0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
161c0 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
161d0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
161e0 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
161f0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16200 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
16210 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
16220 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16230 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
16240 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
16250 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
16260 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
16270 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16280 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
16290 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
162a0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
162b0 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
162c0 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
162d0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
162e0 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
162f0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
16300 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
16310 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
16320 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
16330 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
16340 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
16350 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16360 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
16370 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
16380 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
16390 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
163a0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
163b0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
163c0 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
163d0 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
163e0 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
163f0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
16400 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
16410 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
16420 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
16430 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
16440 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
16450 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
16460 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
16470 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
16480 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
16490 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
164a0 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
164b0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
164c0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
164d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
164e0 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
164f0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
16500 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16510 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
16520 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16530 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
16540 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
16550 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
16560 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
16570 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
16580 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
16590 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
165a0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
165b0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
165c0 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
165d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
165e0 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
165f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16600 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
16610 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
16620 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
16630 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
16640 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
16650 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
16660 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
16670 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
16680 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
16690 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
166a0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
166b0 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
166c0 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
166d0 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
166e0 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
166f0 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
16700 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
16710 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
16720 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
16730 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
16740 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
16750 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
16760 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
16770 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
16780 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
16790 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
167a0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
167b0 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
167c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
167d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
167e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
167f0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
16800 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
16810 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
16820 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
16830 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
16840 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
16850 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
16860 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
16870 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
16880 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
16890 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
168a0 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
168b0 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
168c0 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
168d0 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
168e0 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
168f0 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
16900 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
16910 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
16920 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16930 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
16940 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
16950 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
16960 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
16970 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
16980 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
16990 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
169a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
169b0 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
169c0 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
169d0 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
169e0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
169f0 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
16a00 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
16a10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16a20 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
16a30 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16a40 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
16a50 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
16a60 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
16a70 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
16a80 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
16a90 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
16aa0 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
16ab0 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
16ac0 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
16ad0 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
16ae0 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
16af0 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
16b00 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16b10 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
16b20 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
16b30 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
16b40 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
16b50 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
16b60 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
16b70 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
16b80 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
16b90 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
16ba0 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
16bb0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
16bc0 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
16bd0 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
16be0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
16bf0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
16c00 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
16c10 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
16c20 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
16c30 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
16c40 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
16c50 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
16c60 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
16c70 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
16c80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16c90 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
16ca0 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
16cb0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
16cc0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
16cd0 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
16ce0 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
16cf0 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
16d00 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
16d10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16d20 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
16d30 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16d40 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16d50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
16d60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
16d70 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
16d80 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
16d90 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
16da0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
16db0 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
16dc0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
16dd0 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
16de0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
16df0 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
16e00 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16e10 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
16e20 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
16e30 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
16e40 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
16e50 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
16e60 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
16e70 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
16e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16e90 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
16ea0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16eb0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
16ec0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16ed0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
16ee0 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
16ef0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16f00 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
16f10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16f20 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
16f30 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
16f40 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
16f50 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
16f60 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
16f70 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
16f80 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
16f90 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
16fa0 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
16fb0 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
16fc0 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
16fd0 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
16fe0 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
16ff0 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
17000 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
17010 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
17020 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17030 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17040 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
17050 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17060 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
17070 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17080 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
17090 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
170a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
170b0 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
170c0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
170d0 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
170e0 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
170f0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
17100 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
17110 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
17120 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
17130 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
17140 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
17150 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
17160 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
17170 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
17180 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
17190 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
171a0 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
171b0 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
171c0 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
171d0 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
171e0 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
171f0 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
17200 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
17210 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
17220 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
17230 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
17240 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
17250 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
17260 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b  s value..**.** [
17270 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17280 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a  TMTJRNL_SPILL]].
17290 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
172a0 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
172b0 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ILL.** <dd>^The 
172c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
172d0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74  MTJRNL_SPILL opt
172e0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
172f0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17300 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68  ch.** becomes th
17310 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  e [statement jou
17320 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64  rnal] spill-to-d
17330 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20  isk threshold.  
17340 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a  .** [Statement j
17350 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c  ournals] are hel
17360 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69  d in memory unti
17370 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e  l their size (in
17380 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65   bytes).** excee
17390 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c  ds this threshol
173a0 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e  d, at which poin
173b0 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74  t they are writt
173c0 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f  en to disk..** O
173d0 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f  r if the thresho
173e0 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d  ld is -1, statem
173f0 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65  ent journals are
17400 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20   always held.** 
17410 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d  exclusively in m
17420 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20  emory..** Since 
17430 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a  many statement j
17440 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65  ournals never be
17450 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74  come large, sett
17460 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a  ing the spill.**
17470 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20   threshold to a 
17480 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34  value such as 64
17490 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20  KiB can greatly 
174a0 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e  reduce the amoun
174b0 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75  t of.** I/O requ
174c0 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ired to support 
174d0 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61  statement rollba
174e0 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ck..** The defau
174f0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  lt value for thi
17500 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e  s setting is con
17510 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a  trolled by the.*
17520 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52  * [SQLITE_STMTJR
17530 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c  NL_SPILL] compil
17540 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
17550 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
17560 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17570 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
17580 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
17590 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
175a0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
175b0 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
175c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
175d0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
175e0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
175f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17600 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
17610 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
17620 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
17630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17640 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
17650 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
17660 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
17670 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17680 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
17690 20 20 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c        6  /* No l
176a0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
176b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
176c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
176d0 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
176e0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
176f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17700 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
17710 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
17720 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
17730 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
17740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
17750 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
17760 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
17770 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17780 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
17790 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
177a0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
177b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
177c0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
177d0 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
177e0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
177f0 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
17800 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
17810 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
17820 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
17830 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
17840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17850 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
17860 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
17870 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17880 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
17890 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
178a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
178b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
178c0 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
178d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
178e0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
178f0 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
17900 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
17910 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17920 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
17930 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
17940 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17950 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
17960 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
17970 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
17980 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17990 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
179a0 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
179b0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
179c0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
179d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
179e0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
179f0 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f  AN 20  /* int */
17a00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17a10 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20  CONFIG_SQLLOG   
17a20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c      21  /* xSqll
17a30 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  og, void* */.#de
17a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17a50 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  IG_MMAP_SIZE    
17a60 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69  22  /* sqlite3_i
17a70 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e  nt64, sqlite3_in
17a80 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t64 */.#define S
17a90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
17aa0 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20  32_HEAPSIZE     
17ab0 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   23  /* int nByt
17ac0 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
17ad0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17ae0 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32  E_HDRSZ        2
17af0 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a  4  /* int *psz *
17b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17b10 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20  _CONFIG_PMASZ   
17b20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
17b30 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  /* unsigned int 
17b40 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65  szPma */.#define
17b50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17b60 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20  TMTJRNL_SPILL   
17b70 20 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42     26  /* int nB
17b80 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  yte */.#define S
17b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
17ba0 4c 4c 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  LL_MALLOC       
17bb0 20 32 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20   27  /* boolean 
17bc0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
17bd0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
17be0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
17bf0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
17c00 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
17c10 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
17c20 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
17c30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17c40 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
17c50 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
17c60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17c70 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
17c80 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
17c90 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
17ca0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
17cb0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
17cc0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
17cd0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
17ce0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
17cf0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
17d00 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
17d10 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
17d20 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
17d30 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
17d40 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
17d50 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17d60 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
17d70 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
17d80 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
17d90 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
17da0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
17db0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
17dc0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
17dd0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
17de0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
17df0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
17e00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
17e10 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
17e20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
17e30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17e40 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
17e50 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17e60 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
17e70 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
17e80 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
17e90 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
17ea0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
17eb0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
17ec0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
17ed0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17ee0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
17ef0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
17f00 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
17f10 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
17f20 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
17f30 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
17f40 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
17f50 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
17f60 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
17f70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17f80 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
17f90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
17fa0 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
17fb0 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
17fc0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
17fd0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
17fe0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
17ff0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
18000 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
18010 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
18020 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
18030 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
18040 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
18050 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
18060 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
18070 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
18080 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
18090 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
180a0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
180b0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
180c0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
180d0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
180e0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
180f0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
18100 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
18110 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
18120 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
18130 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
18140 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
18150 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
18160 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18170 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
18180 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
18190 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
181a0 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
181b0 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
181c0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
181d0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
181e0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
181f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
18200 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
18210 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
18220 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
18230 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
18240 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
18250 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
18260 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
18270 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
18280 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
18290 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
182a0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
182b0 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
182c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
182d0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
182e0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
182f0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
18300 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
18310 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
18320 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
18330 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
18340 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
18350 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
18360 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
18370 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
18380 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
18390 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
183a0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
183b0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
183c0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
183d0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
183e0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
183f0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
18400 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
18410 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
18420 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
18430 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
18440 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
18450 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
18460 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
18470 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
18480 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
18490 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
184a0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
184b0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
184c0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
184d0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
184e0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
184f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18500 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18510 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18520 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18530 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18540 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
18550 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
18560 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
18570 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
18580 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18590 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
185a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
185b0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
185c0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
185d0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
185e0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
185f0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
18600 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18610 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
18620 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18630 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18640 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18650 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
18660 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
18670 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
18680 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
18690 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
186a0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
186b0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
186c0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
186d0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
186e0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
186f0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
18700 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
18710 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
18720 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
18730 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
18740 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
18750 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
18760 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
18770 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18780 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18790 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
187a0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
187b0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
187c0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
187d0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
187e0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
187f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
18800 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
18810 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
18820 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18830 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
18840 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18850 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18860 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f  FTS3_TOKENIZER</
18870 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
18880 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
18890 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
188a0 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72  sable the two-ar
188b0 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f  gument.** versio
188c0 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74  n of the [fts3_t
188d0 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63  okenizer()] func
188e0 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61  tion which is pa
188f0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54  rt of the.** [FT
18900 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65  S3] full-text se
18910 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65  arch engine exte
18920 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  nsion..** There 
18930 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
18940 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18950 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
18960 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
18970 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
18980 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74   0 to disable ft
18990 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f  s3_tokenizer() o
189a0 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  r.** positive to
189b0 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b   enable fts3_tok
189c0 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61  enizer() or nega
189d0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
189e0 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
189f0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
18a00 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18a10 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18a20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18a30 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
18a40 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
18a50 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66  dicate whether f
18a60 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73  ts3_tokenizer is
18a70 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18a80 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
18a90 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18aa0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18ab0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
18ac0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
18ad0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
18ae0 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  ew setting is no
18af0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
18b00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
18b10 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
18b20 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
18b30 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENSION</dt>.** <
18b40 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18b50 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
18b60 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
18b70 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
18b80 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20  extension()].** 
18b90 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65  interface indepe
18ba0 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b  ndently of the [
18bb0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18bc0 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  ] SQL function..
18bd0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
18be0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
18bf0 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61  nsion()] API ena
18c00 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
18c10 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41   both the.** C-A
18c20 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  PI [sqlite3_load
18c30 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e  _extension()] an
18c40 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
18c50 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  on [load_extensi
18c60 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  on()]..** There 
18c70 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
18c80 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18c90 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  ts..** When the 
18ca0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
18cb0 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  o this interface
18cc0 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79   is 1, then only
18cd0 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a   the C-API is.**
18ce0 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65   enabled and the
18cf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
18d00 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20  mains disabled. 
18d10 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72   If the first ar
18d20 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69  gument to.** thi
18d30 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30  s interface is 0
18d40 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20  , then both the 
18d50 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51  C-API and the SQ
18d60 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64  L function are d
18d70 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74  isabled..** If t
18d80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18d90 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f  t is -1, then no
18da0 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64   changes are mad
18db0 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69  e to state of ei
18dc0 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50  ther the.** C-AP
18dd0 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e  I or the SQL fun
18de0 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65  ction..** The se
18df0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
18e00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18e10 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
18e20 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
18e30 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
18e40 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73  icate whether [s
18e50 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18e60 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
18e70 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65  ce.** is disable
18e80 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c  d or enabled fol
18e90 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
18ea0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
18eb0 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62  rameter may.** b
18ec0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18ed0 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
18ee0 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20  the new setting 
18ef0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
18f00 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  back..** </dd>.*
18f10 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18f20 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e  DBCONFIG_MAINDBN
18f30 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  AME</dt>.** <dd>
18f40 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
18f50 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
18f60 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18f70 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a  "main" database.
18f80 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65  ** schema.  ^The
18f90 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69   sole argument i
18fa0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18fb0 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73   constant UTF8 s
18fc0 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77  tring.** which w
18fd0 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e  ill become the n
18fe0 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69  ew schema name i
18ff0 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e  n place of "main
19000 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64  ".  ^SQLite.** d
19010 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63  oes not make a c
19020 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d  opy of the new m
19030 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20  ain schema name 
19040 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61  string, so the a
19050 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
19060 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
19070 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  he argument pass
19080 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43  ed into this DBC
19090 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20  ONFIG option is 
190a0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74  unchanged.** unt
190b0 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61 74  il after the dat
190c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
190d0 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64   closes..** </dd
190e0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
190f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
19100 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74  KPT_ON_CLOSE</dt
19110 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c  >.** <dd> Usuall
19120 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  y, when a databa
19130 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69  se in wal mode i
19140 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61  s closed or deta
19150 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20  ched from a .** 
19160 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c  database handle,
19170 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69   SQLite checks i
19180 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e  f this will mean
19190 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20   that there are 
191a0 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65  now no .** conne
191b0 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f  ctions at all to
191c0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49   the database. I
191d0 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d  f so, it perform
191e0 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a  s a checkpoint .
191f0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66  ** operation bef
19200 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20  ore closing the 
19210 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73  connection. This
19220 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75   option may be u
19230 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69  sed to.** overri
19240 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75  de this behaviou
19250 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72  r. The first par
19260 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
19270 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a   this operation.
19280 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ** is an integer
19290 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64   - non-zero to d
192a0 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e  isable checkpoin
192b0 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20  ts-on-close, or 
192c0 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66  zero (the.** def
192d0 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20  ault) to enable 
192e0 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64  them. The second
192f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19300 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19310 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68  teger.** into wh
19320 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30  ich is written 0
19330 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19340 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70  e whether checkp
19350 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a  oints-on-close.*
19360 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61  * have been disa
19370 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79  bled - 0 if they
19380 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65   are not disable
19390 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65  d, 1 if they are
193a0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
193b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
193c0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47  NFIG_ENABLE_QPSG
193d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54  </dt>.** <dd>^(T
193e0 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
193f0 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f  IG_ENABLE_QPSG o
19400 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73 20  ption activates 
19410 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a 2a  or deactivates.*
19420 2a 20 74 68 65 20 5b 71 75 65 72 79 20 70 6c 61  * the [query pla
19430 6e 6e 65 72 20 73 74 61 62 69 6c 69 74 79 20 67  nner stability g
19440 75 61 72 61 6e 74 65 65 5d 20 28 51 50 53 47 29  uarantee] (QPSG)
19450 2e 20 20 57 68 65 6e 20 74 68 65 20 51 50 53 47  .  When the QPSG
19460 20 69 73 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61   is active,.** a
19470 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 72   single SQL quer
19480 79 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  y statement will
19490 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20   always use the 
194a0 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 72  same algorithm r
194b0 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
194c0 76 61 6c 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64  values of [bound
194d0 20 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20   parameters].)^ 
194e0 54 68 65 20 51 50 53 47 20 64 69 73 61 62 6c 65  The QPSG disable
194f0 73 20 73 6f 6d 65 20 71 75 65 72 79 20 6f 70 74  s some query opt
19500 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68  imizations.** th
19510 61 74 20 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76  at look at the v
19520 61 6c 75 65 73 20 6f 66 20 62 6f 75 6e 64 20 70  alues of bound p
19530 61 72 61 6d 65 74 65 72 73 2c 20 77 68 69 63 68  arameters, which
19540 20 63 61 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71   can make some q
19550 75 65 72 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72  ueries.** slower
19560 2e 20 20 42 75 74 20 74 68 65 20 51 50 53 47 20  .  But the QPSG 
19570 68 61 73 20 74 68 65 20 61 64 76 61 6e 74 61 67  has the advantag
19580 65 20 6f 66 20 6d 6f 72 65 20 70 72 65 64 69 63  e of more predic
19590 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 20  table behavior. 
195a0 20 57 69 74 68 0a 2a 2a 20 74 68 65 20 51 50 53   With.** the QPS
195b0 47 20 61 63 74 69 76 65 2c 20 53 51 4c 69 74 65  G active, SQLite
195c0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65   will always use
195d0 20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79 20   the same query 
195e0 70 6c 61 6e 20 69 6e 20 74 68 65 20 66 69 65 6c  plan in the fiel
195f0 64 20 61 73 0a 2a 2a 20 77 61 73 20 75 73 65 64  d as.** was used
19600 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
19610 69 6e 20 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 3c  in the lab..** <
19620 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
19630 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
19640 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
19650 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  DBNAME          
19660 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20    1000 /* const 
19670 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  char* */.#define
19680 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19690 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
196a0 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76         1001 /* v
196b0 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
196c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
196d0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
196e0 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30  KEY           10
196f0 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  02 /* int int* *
19700 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19710 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19720 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
19730 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1003 /* int int*
19740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19750 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19760 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
19770 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e  R 1004 /* int in
19780 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
19790 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
197a0 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
197b0 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20  ION 1005 /* int 
197c0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
197d0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
197e0 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
197f0 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e        1006 /* in
19800 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
19810 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19820 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20  G_ENABLE_QPSG   
19830 20 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20          1007 /* 
19840 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
19850 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
19860 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
19870 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
19880 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
19890 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
198a0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
198b0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
198c0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
198d0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
198e0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
198f0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
19900 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
19910 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
19920 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
19930 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
19940 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
19950 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
19960 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
19970 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
19980 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
19990 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
199a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
199b0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
199c0 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
199d0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
199e0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
199f0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
19a00 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
19a10 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
19a20 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
19a30 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
19a40 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
19a50 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
19a60 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
19a70 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
19a80 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
19a90 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
19aa0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
19ab0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
19ac0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
19ad0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
19ae0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
19af0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
19b00 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
19b10 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
19b20 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
19b30 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
19b40 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
19b50 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
19b60 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
19b70 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
19b80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19b90 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19ba0 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
19bb0 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  ce usually retur
19bc0 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
19bd0 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  f.** the most re
19be0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
19bf0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
19c00 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
19c10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
19c20 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
19c30 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73  nnection D. ^Ins
19c40 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
19c50 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
19c60 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f   are not.** reco
19c70 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63  rded. ^If no suc
19c80 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
19c90 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
19ca0 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63  les have ever oc
19cb0 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68  curred .** on th
19cc0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19cd0 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71  ction D, then sq
19ce0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
19cf0 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
19d00 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a  ns .** zero..**.
19d10 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65  ** As well as be
19d20 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69  ing set automati
19d30 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72  cally as rows ar
19d40 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  e inserted into 
19d50 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
19d60 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
19d70 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
19d80 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73  unction may be s
19d90 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79  et explicitly by
19da0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
19db0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19dc0 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  id()].**.** Some
19dd0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
19de0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
19df0 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69  ay INSERT rows i
19e00 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
19e10 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63   as.** part of c
19e20 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e  ommitting a tran
19e30 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f  saction (e.g. to
19e40 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75   flush data accu
19e50 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72  mulated in memor
19e60 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49  y.** to disk). I
19e70 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73  n this case subs
19e80 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
19e90 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
19ea0 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
19eb0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
19ec0 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c  h these internal
19ed0 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f   INSERT operatio
19ee0 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20  ns, which leads 
19ef0 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69  to .** unintuiti
19f00 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74  ve results. Virt
19f10 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
19f20 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64  entations that d
19f30 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64  o write to rowid
19f40 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68  .** tables in th
19f50 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64  is way can avoid
19f60 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79   this problem by
19f70 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f   restoring the o
19f80 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69  riginal .** rowi
19f90 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73  d value using [s
19fa0 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
19fb0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
19fc0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
19fd0 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20   .** control to 
19fe0 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20  the user..**.** 
19ff0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
1a000 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
1a010 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68   trigger then th
1a020 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
1a030 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b  .** return the [
1a040 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
1a050 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f  serted row as lo
1a060 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
1a070 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67  r is .** running
1a080 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67  . Once the trigg
1a090 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c  er program ends,
1a0a0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a0b0 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
1a0c0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
1a0d0 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
1a0e0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
1a0f0 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a  r was fired.)^.*
1a100 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
1a110 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
1a120 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
1a130 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
1a140 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
1a150 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
1a160 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
1a170 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a180 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
1a190 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
1a1a0 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
1a1b0 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
1a1c0 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
1a1d0 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
1a1e0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
1a1f0 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
1a200 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
1a210 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
1a220 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
1a230 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
1a240 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
1a250 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
1a260 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
1a270 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
1a280 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
1a290 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
1a2a0 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
1a2b0 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
1a2c0 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
1a2d0 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
1a2e0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
1a2f0 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
1a300 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
1a310 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
1a320 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1a330 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
1a340 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
1a350 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
1a360 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
1a370 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
1a380 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
1a390 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
1a3a0 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
1a3b0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
1a3c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
1a3d0 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
1a3e0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
1a3f0 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
1a400 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1a410 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
1a420 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1a430 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
1a440 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
1a450 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
1a460 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1a470 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
1a480 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
1a490 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1a4a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
1a4b0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
1a4c0 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
1a4d0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
1a4e0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
1a4f0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1a500 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
1a510 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
1a520 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
1a530 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
1a540 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
1a550 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
1a560 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
1a570 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
1a580 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1a590 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1a5a0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
1a5b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1a5c0 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65  et the Last Inse
1a5d0 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a  rt Rowid value..
1a5e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1a5f0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
1a600 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1a610 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29  sert_rowid(D, R)
1a620 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74   method allows t
1a630 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
1a640 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c  o.** set the val
1a650 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63  ue returned by c
1a660 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c  alling sqlite3_l
1a670 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a680 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74  (D) to R .** wit
1a690 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61  hout inserting a
1a6a0 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61   row into the da
1a6b0 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20  tabase..*/.void 
1a6c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1a6d0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
1a6e0 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69  lite3*,sqlite3_i
1a6f0 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
1a700 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
1a710 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
1a720 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1a730 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1a740 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1a750 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
1a760 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
1a770 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
1a780 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1a790 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1a7a0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
1a7b0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1a7c0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
1a7d0 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
1a7e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
1a7f0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
1a800 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
1a810 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
1a820 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1a830 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
1a840 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
1a850 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1a860 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
1a870 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
1a880 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
1a890 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
1a8a0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a8b0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1a8c0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
1a8d0 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
1a8e0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
1a8f0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
1a900 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
1a910 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
1a920 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
1a930 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
1a940 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
1a950 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
1a960 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
1a970 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1a980 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
1a990 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
1a9a0 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
1a9b0 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
1a9c0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
1a9d0 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
1a9e0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1a9f0 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
1aa00 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
1aa10 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1aa20 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
1aa30 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
1aa40 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
1aa50 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
1aa60 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
1aa70 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
1aa80 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
1aa90 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
1aaa0 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
1aab0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1aac0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
1aad0 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
1aae0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1aaf0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
1ab00 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
1ab10 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
1ab20 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
1ab30 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1ab40 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
1ab50 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
1ab60 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
1ab70 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1ab80 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
1ab90 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
1aba0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
1abb0 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
1abc0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1abd0 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
1abe0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1abf0 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
1ac00 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1ac10 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
1ac20 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
1ac30 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
1ac40 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
1ac50 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
1ac60 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
1ac70 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
1ac80 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
1ac90 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
1aca0 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
1acb0 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
1acc0 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
1acd0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1ace0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1acf0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1ad00 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
1ad10 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
1ad20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
1ad30 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
1ad40 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
1ad50 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
1ad60 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
1ad70 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
1ad80 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1ad90 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
1ada0 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
1adb0 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
1adc0 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
1add0 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
1ade0 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
1adf0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
1ae00 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
1ae10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
1ae20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
1ae30 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
1ae40 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1ae50 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1ae60 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1ae70 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
1ae80 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
1ae90 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
1aea0 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
1aeb0 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
1aec0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
1aed0 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
1aee0 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
1aef0 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
1af00 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1af10 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
1af20 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1af30 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
1af40 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1af50 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1af60 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
1af70 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1af80 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1af90 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
1afa0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
1afb0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1afc0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1afd0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
1afe0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
1aff0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
1b000 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1b010 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1b020 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1b030 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1b040 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1b050 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1b060 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1b070 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1b080 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1b090 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1b0a0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
1b0b0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1b0c0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1b0d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
1b0e0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1b0f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b100 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
1b110 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1b120 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1b130 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1b140 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1b150 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
1b160 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
1b170 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
1b180 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
1b190 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
1b1a0 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
1b1b0 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
1b1c0 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
1b1d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b1e0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
1b1f0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
1b200 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
1b210 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
1b220 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
1b230 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1b240 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1b250 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
1b260 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
1b270 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1b280 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1b290 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
1b2a0 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
1b2b0 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
1b2c0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
1b2d0 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
1b2e0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
1b2f0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
1b300 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
1b310 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1b320 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
1b330 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
1b340 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1b350 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
1b360 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
1b370 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
1b380 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
1b390 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1b3a0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1b3b0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1b3c0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1b3d0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
1b3e0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
1b3f0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1b400 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1b410 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1b420 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1b430 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1b440 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1b450 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1b460 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1b470 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1b480 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1b490 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1b4a0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1b4b0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
1b4c0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1b4d0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1b4e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1b4f0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
1b500 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20  unning Query.** 
1b510 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1b520 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1b530 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
1b540 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
1b550 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
1b560 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
1b570 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
1b580 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
1b590 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
1b5a0 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
1b5b0 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
1b5c0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
1b5d0 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
1b5e0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
1b5f0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
1b600 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
1b610 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
1b620 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
1b630 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
1b640 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
1b650 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1b660 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
1b670 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
1b680 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
1b690 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
1b6a0 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
1b6b0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
1b6c0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
1b6d0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1b6e0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1b6f0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1b700 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
1b710 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
1b720 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
1b730 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b740 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
1b750 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
1b760 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
1b770 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
1b780 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
1b790 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
1b7a0 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
1b7b0 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
1b7c0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
1b7d0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
1b7e0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
1b7f0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
1b800 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
1b810 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
1b820 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
1b830 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
1b840 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1b850 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
1b860 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
1b870 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
1b880 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
1b890 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1b8a0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
1b8b0 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
1b8c0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
1b8d0 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
1b8e0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
1b8f0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
1b900 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
1b910 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b920 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
1b930 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
1b940 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
1b950 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
1b960 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
1b970 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b980 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
1b990 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
1b9a0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1b9b0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1b9c0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1b9d0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1b9e0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
1b9f0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
1ba00 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
1ba10 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
1ba20 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
1ba30 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
1ba40 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
1ba50 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1ba60 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
1ba70 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1ba80 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1ba90 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
1baa0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1bab0 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
1bac0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
1bad0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
1bae0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1baf0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
1bb00 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
1bb10 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
1bb20 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
1bb30 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
1bb40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1bb50 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
1bb60 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
1bb70 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1bb80 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1bb90 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1bba0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1bbb0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f  call returns..*/
1bbc0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
1bbd0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
1bbe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bbf0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
1bc00 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1bc10 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
1bc20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1bc30 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
1bc40 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
1bc50 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
1bc60 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
1bc70 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
1bc80 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
1bc90 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
1bca0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
1bcb0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
1bcc0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
1bcd0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
1bce0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
1bcf0 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
1bd00 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
1bd10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
1bd20 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
1bd30 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
1bd40 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
1bd50 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
1bd60 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
1bd70 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
1bd80 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
1bd90 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
1bda0 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
1bdb0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
1bdc0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
1bdd0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
1bde0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
1bdf0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
1be00 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
1be10 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
1be20 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
1be30 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
1be40 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
1be50 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
1be60 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
1be70 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
1be80 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
1be90 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
1bea0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
1beb0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
1bec0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
1bed0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
1bee0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
1bef0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
1bf00 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
1bf10 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
1bf20 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1bf30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
1bf40 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
1bf50 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
1bf60 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
1bf70 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
1bf80 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
1bf90 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
1bfa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1bfb0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
1bfc0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
1bfd0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
1bfe0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
1bff0 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
1c000 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
1c010 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
1c020 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
1c030 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
1c040 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1c050 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
1c060 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
1c070 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
1c080 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
1c090 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
1c0a0 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
1c0b0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
1c0c0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
1c0d0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
1c0e0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
1c0f0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
1c100 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
1c110 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1c120 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
1c130 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
1c140 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1c150 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
1c160 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
1c170 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1c180 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1c190 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
1c1a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1c1b0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
1c1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1c1d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1c1e0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
1c1f0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1c200 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
1c210 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
1c220 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
1c230 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1c240 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
1c250 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
1c260 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
1c270 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
1c280 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c290 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
1c2a0 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
1c2b0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
1c2c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62  .** KEYWORDS: {b
1c2d0 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
1c2e0 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64  back} {busy hand
1c2f0 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
1c300 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1c310 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1c320 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72  handler(D,X,P) r
1c330 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
1c340 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1c350 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20  X.** that might 
1c360 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1c370 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
1c380 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
1c390 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  t is made to acc
1c3a0 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74  ess a database t
1c3b0 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20  able associated 
1c3c0 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  with.** [databas
1c3d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1c3e0 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72  when another thr
1c3f0 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
1c400 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20  s has the table 
1c410 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73  locked..** The s
1c420 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c430 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  ler() interface 
1c440 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  is used to imple
1c450 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ment.** [sqlite3
1c460 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1c470 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73   and [PRAGMA bus
1c480 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a  y_timeout]..**.*
1c490 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
1c4a0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
1c4b0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
1c4c0 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  SY].** is return
1c4d0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
1c4e0 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
1c4f0 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
1c500 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1c510 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
1c520 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
1c530 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
1c540 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
1c550 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
1c560 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1c570 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
1c580 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
1c590 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
1c5a0 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
1c5b0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
1c5c0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1c5d0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
1c5e0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
1c5f0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
1c600 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
1c610 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
1c620 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
1c630 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
1c640 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
1c650 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c  nvoked previousl
1c660 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c  y for the same l
1c670 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
1c680 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
1c690 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1c6a0 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
1c6b0 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
1c6c0 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
1c6d0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1c6e0 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
1c6f0 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a  SY] is returned.
1c700 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1c710 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
1c720 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1c730 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1c740 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
1c750 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
1c760 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1c770 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ase and the cycl
1c780 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
1c790 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
1c7a0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
1c7b0 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
1c7c0 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
1c7d0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
1c7e0 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
1c7f0 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
1c800 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
1c810 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
1c820 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
1c830 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
1c840 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
1c850 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
1c860 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
1c870 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f  LITE_BUSY].** to
1c880 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1c890 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
1c8a0 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73  king the .** bus
1c8b0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
1c8c0 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
1c8d0 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
1c8e0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1c8f0 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
1c900 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
1c910 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
1c920 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
1c930 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
1c940 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1c950 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1c960 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
1c970 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
1c980 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
1c990 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
1c9a0 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
1c9b0 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
1c9c0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1c9d0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1c9e0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
1c9f0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
1ca00 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
1ca10 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1ca20 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
1ca30 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
1ca40 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
1ca50 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
1ca60 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
1ca70 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
1ca80 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
1ca90 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
1caa0 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
1cab0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
1cac0 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
1cad0 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
1cae0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1caf0 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
1cb00 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
1cb10 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
1cb20 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
1cb30 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
1cb40 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
1cb50 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
1cb60 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1cb70 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1cb80 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1cb90 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
1cba0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1cbb0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
1cbc0 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
1cbd0 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
1cbe0 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
1cbf0 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
1cc00 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
1cc10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1cc20 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
1cc30 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50  or evaluating [P
1cc40 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1cc50 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67  ut=N] will chang
1cc60 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61  e the.** busy ha
1cc70 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63  ndler and thus c
1cc80 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75  lear any previou
1cc90 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e  sly set busy han
1cca0 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
1ccb0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
1ccc0 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
1ccd0 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
1cce0 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
1ccf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cd00 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1cd10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1cd20 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
1cd30 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  ,.** the busy ha
1cd40 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65  ndler is not ree
1cd50 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63  ntrant.  Any suc
1cd60 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
1cd70 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
1cd80 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
1cd90 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
1cda0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
1cdb0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1cdc0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
1cdd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1cde0 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
1cdf0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1ce00 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1ce10 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
1ce20 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f  lite3*,int(*)(vo
1ce30 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b  id*,int),void*);
1ce40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ce50 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1ce60 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eout.** METHOD: 
1ce70 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1ce80 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1ce90 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1cea0 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1ceb0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1cec0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1ced0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1cee0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1cef0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1cf00 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1cf10 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1cf20 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1cf30 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1cf40 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1cf50 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1cf60 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1cf70 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1cf80 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1cf90 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1cfa0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1cfb0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1cfc0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1cfd0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1cfe0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
1cff0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
1d000 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1d010 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
1d020 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
1d030 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
1d040 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
1d050 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
1d060 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1d070 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1d080 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
1d090 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1d0a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d0b0 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
1d0c0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
1d0d0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
1d0e0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
1d0f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
1d100 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
1d110 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1d120 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
1d130 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
1d140 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
1d150 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
1d160 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
1d170 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
1d180 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1d190 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
1d1a0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
1d1b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1d1c0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
1d1d0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
1d1e0 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f  Queries.** METHO
1d1f0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1d200 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1d210 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1d220 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1d230 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1d240 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1d250 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1d260 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1d270 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1d280 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1d290 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1d2a0 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1d2b0 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1d2c0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1d2d0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1d2e0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1d2f0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1d300 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1d310 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1d320 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1d330 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1d340 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1d350 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1d360 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1d370 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1d380 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1d390 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1d3a0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1d3b0 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1d3c0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1d3d0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1d3e0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1d3f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1d400 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1d410 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1d420 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1d430 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1d440 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1d450 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1d460 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1d470 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1d480 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1d490 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1d4a0 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1d4b0 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1d4c0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1d4d0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1d4e0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1d4f0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1d500 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1d510 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1d520 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1d530 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1d540 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1d550 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1d560 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1d570 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1d580 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1d590 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1d5a0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1d5b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1d5c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1d5d0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1d5e0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1d5f0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1d600 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1d610 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1d620 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1d630 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1d640 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1d650 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1d660 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1d670 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1d680 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1d690 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1d6a0 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1d6b0 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1d6c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1d6d0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1d6e0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1d6f0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1d700 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1d710 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1d720 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1d730 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1d740 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1d750 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1d760 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1d770 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1d780 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1d790 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1d7a0 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1d7b0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1d7c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1d7d0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1d7e0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1d7f0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1d800 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1d810 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1d820 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1d830 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1d840 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1d850 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1d860 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1d870 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1d880 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1d890 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1d8a0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1d8b0 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1d8c0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1d8d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1d8e0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1d8f0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1d900 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1d910 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d920 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1d930 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1d940 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1d950 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d960 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1d970 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1d980 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1d990 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1d9a0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1d9b0 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1d9c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d9d0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1d9e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d9f0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1da00 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1da10 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1da20 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1da30 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1da40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1da50 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1da60 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1da70 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1da80 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1da90 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1daa0 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1dab0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1dac0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1dad0 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1dae0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1daf0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1db00 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1db10 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1db20 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1db30 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1db40 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1db50 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1db60 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1db70 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1db80 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1db90 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1dba0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1dbb0 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1dbc0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1dbd0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1dbe0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1dbf0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1dc00 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1dc10 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1dc20 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1dc30 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1dc40 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1dc50 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1dc60 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1dc70 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1dc80 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1dc90 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1dca0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1dcb0 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1dcc0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1dcd0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1dce0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1dcf0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1dd00 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1dd10 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1dd20 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1dd30 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1dd40 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1dd50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1dd60 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1dd70 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1dd80 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1dd90 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1dda0 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1ddb0 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1ddc0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1ddd0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1dde0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1ddf0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1de00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1de10 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1de20 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1de30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1de40 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1de50 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1de60 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1de70 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1de80 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1de90 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1dea0 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1deb0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1dec0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1ded0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1dee0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1def0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1df00 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1df10 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1df20 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1df30 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1df40 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1df50 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1df60 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1df70 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1df80 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1df90 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1dfa0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1dfb0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1dfc0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1dfd0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1dfe0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1dff0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1e000 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1e010 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1e020 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1e030 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1e040 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1e050 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1e060 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ry..** These rou
1e070 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64  tines understand
1e080 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d   most of the com
1e090 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69  mon K&R formatti
1e0a0 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70  ng options,.** p
1e0b0 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  lus some additio
1e0c0 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64  nal non-standard
1e0d0 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c   formats, detail
1e0e0 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74  ed below..** Not
1e0f0 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74  e that some of t
1e100 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20  he more obscure 
1e110 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1e120 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a  ns from recent.*
1e130 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e  * C-library stan
1e140 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65  dards are omitte
1e150 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c  d from this impl
1e160 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ementation..**.*
1e170 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1e180 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1e190 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1e1a0 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1e1b0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1e1c0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1e1d0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1e1e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
1e1f0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1e200 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
1e210 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
1e220 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
1e230 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
1e240 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
1e250 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
1e260 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1e270 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
1e280 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
1e290 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1e2a0 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1e2b0 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1e2c0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1e2d0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1e2e0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1e2f0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1e300 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1e310 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1e320 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1e330 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1e340 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1e350 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1e360 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1e370 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1e380 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1e390 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1e3a0 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1e3b0 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1e3c0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1e3d0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1e3e0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1e3f0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1e400 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1e410 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1e420 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1e430 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1e440 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1e450 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1e460 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1e470 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1e480 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1e490 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1e4a0 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1e4b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1e4c0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1e4d0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1e4e0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1e4f0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1e500 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1e510 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1e520 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1e530 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1e540 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1e550 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1e560 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1e570 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1e580 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1e590 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1e5a0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1e5b0 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1e5c0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1e5d0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1e5e0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1e5f0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1e600 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1e610 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1e620 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1e630 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1e640 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1e650 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1e660 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1e670 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1e680 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1e690 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1e6a0 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1e6b0 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1e6c0 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1e6d0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1e6e0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
1e6f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e700 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
1e710 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
1e720 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
1e730 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1e740 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1e750 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
1e760 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
1e770 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
1e780 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
1e790 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
1e7a0 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
1e7b0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
1e7c0 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
1e7d0 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
1e7e0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
1e7f0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
1e800 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
1e810 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77   "%q", "%Q", "%w
1e820 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  " and "%z" optio
1e830 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1e840 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1e850 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1e860 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1e870 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1e880 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1e890 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1e8a0 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1e8b0 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1e8c0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1e8d0 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1e8e0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1e8f0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1e900 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1e910 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1e920 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1e930 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1e940 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1e950 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1e960 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1e970 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1e980 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1e990 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1e9a0 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1e9b0 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1e9c0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e9d0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1e9e0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1e9f0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1ea00 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1ea10 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1ea20 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1ea30 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1ea40 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1ea50 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ea60 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1ea70 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1ea80 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1ea90 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1eaa0 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1eab0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1eac0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1ead0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1eae0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1eaf0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1eb00 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1eb10 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1eb20 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1eb30 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1eb40 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1eb50 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1eb60 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
1eb70 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
1eb80 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1eb90 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1eba0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1ebb0 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
1ebc0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
1ebd0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ebe0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1ebf0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
1ec00 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
1ec10 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
1ec20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
1ec30 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
1ec40 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
1ec50 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1ec60 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1ec70 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1ec80 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
1ec90 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
1eca0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1ecb0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
1ecc0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
1ecd0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
1ece0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
1ecf0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
1ed00 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
1ed10 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
1ed20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
1ed30 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
1ed40 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
1ed50 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
1ed60 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
1ed70 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
1ed80 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
1ed90 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
1eda0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
1edb0 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
1edc0 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
1edd0 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
1ede0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
1edf0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
1ee00 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
1ee10 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
1ee20 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
1ee30 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
1ee40 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
1ee50 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
1ee60 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
1ee70 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1ee80 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1ee90 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1eea0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1eeb0 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
1eec0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1eed0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1eee0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1eef0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1ef00 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1ef10 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1ef20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
1ef30 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
1ef40 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
1ef50 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
1ef60 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
1ef70 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
1ef80 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
1ef90 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1efa0 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74  (The "%w" format
1efb0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c  ting option is l
1efc0 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20  ike "%q" except 
1efd0 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20  that it expects 
1efe0 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e  to.** be contain
1eff0 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65  ed within double
1f000 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20  -quotes instead 
1f010 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  of single quotes
1f020 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61  , and it.** esca
1f030 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71  pes the double-q
1f040 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69  uote character i
1f050 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69  nstead of the si
1f060 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68  ngle-quote.** ch
1f070 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20  aracter.)^  The 
1f080 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1f090 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64  option is intend
1f0a0 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e  ed for safely in
1f0b0 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65  serting.** table
1f0c0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   and column name
1f0d0 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75  s into a constru
1f0e0 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  cted SQL stateme
1f0f0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  nt..**.** ^(The 
1f100 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
1f110 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1f120 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
1f130 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
1f140 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
1f150 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
1f160 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
1f170 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
1f180 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
1f190 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
1f1a0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1f1b0 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  g.)^.*/.char *sq
1f1c0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1f1d0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1f1e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1f1f0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1f200 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
1f210 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1f220 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1f230 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1f240 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1f250 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1f260 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1f270 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1f280 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1f290 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1f2a0 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1f2b0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1f2c0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1f2d0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1f2e0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1f2f0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1f300 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1f310 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1f320 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1f330 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1f340 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1f350 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1f360 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1f370 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1f380 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1f390 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1f3a0 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1f3b0 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1f3c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1f3d0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1f3e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1f3f0 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1f400 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1f410 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1f420 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1f430 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1f440 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1f450 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1f460 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1f470 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1f480 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1f490 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1f4a0 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1f4b0 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1f4c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1f4d0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1f4e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1f4f0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1f500 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1f510 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1f520 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29  ite3_malloc64(N)
1f530 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a   routine works j
1f540 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69  ust like.** sqli
1f550 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78  te3_malloc(N) ex
1f560 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61  cept that N is a
1f570 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69  n unsigned 64-bi
1f580 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  t integer instea
1f590 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64  d.** of a signed
1f5a0 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e   32-bit integer.
1f5b0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1f5c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
1f5d0 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
1f5e0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
1f5f0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1f600 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1f610 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1f620 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
1f630 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
1f640 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
1f650 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1f660 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
1f670 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
1f680 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1f690 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1f6a0 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
1f6b0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
1f6c0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
1f6d0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
1f6e0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
1f6f0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
1f700 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
1f710 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
1f720 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
1f730 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
1f740 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
1f750 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
1f760 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
1f770 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
1f780 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
1f790 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
1f7a0 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
1f7b0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1f7c0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
1f7d0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
1f7e0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
1f7f0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
1f800 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
1f810 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
1f820 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1f830 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1f840 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
1f850 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1f860 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72  alloc(X,N) inter
1f870 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1f880 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1f890 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1f8a0 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20  tion X to be at 
1f8b0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a  least N bytes..*
1f8c0 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61  * ^If the X para
1f8d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1f8e0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a  _realloc(X,N).**
1f8f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1f900 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1f910 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1f920 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1f930 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1f940 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20  )..** ^If the N 
1f950 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1f960 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f970 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1f980 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1f990 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1f9a0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1f9b0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1f9c0 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a  ite3_free(X)..**
1f9d0 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1f9e0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61  c(X,N) returns a
1f9f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1fa00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1fa10 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1fa20 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1fa30 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66  r NULL if insuff
1fa40 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1fa50 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e   available..** ^
1fa60 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1fa70 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1fa80 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1fa90 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1faa0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1fab0 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1fac0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1fad0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1fae0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1faf0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fb00 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69  X,N) and the pri
1fb10 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1fb20 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
1fb30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1fb40 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,N) returns NULL
1fb50 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69   and N is positi
1fb60 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  ve, then the.** 
1fb70 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1fb80 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1fb90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1fba0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29  3_realloc64(X,N)
1fbb0 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b   interfaces work
1fbc0 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a  s the same as.**
1fbd0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fbe0 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61  (X,N) except tha
1fbf0 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20  t N is a 64-bit 
1fc00 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
1fc10 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1fc20 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
1fc30 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nteger..**.** ^I
1fc40 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20  f X is a memory 
1fc50 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69  allocation previ
1fc60 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
1fc70 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1fc80 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1fc90 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c  _malloc64(), sql
1fca0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20  ite3_realloc(), 
1fcb0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1fcc0 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20  oc64(), then.** 
1fcd0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1fce0 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
1fcf0 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79  e of that memory
1fd00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62   allocation in b
1fd10 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61  ytes..** ^The va
1fd20 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1fd30 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1fd40 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
1fd50 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72   than the number
1fd60 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71  .** of bytes req
1fd70 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61  uested when X wa
1fd80 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49  s allocated.  ^I
1fd90 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f X is a NULL po
1fda0 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71  inter then.** sq
1fdb0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1fdc0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66  eturns zero.  If
1fdd0 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d   X points to som
1fde0 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e  ething that is n
1fdf0 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e  ot.** the beginn
1fe00 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ing of memory al
1fe10 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20  location, or if 
1fe20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66  it points to a f
1fe30 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64  ormerly.** valid
1fe40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fe50 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20  on that has now 
1fe60 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e  been freed, then
1fe70 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
1fe80 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   of sqlite3_msiz
1fe90 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65  e(X) is undefine
1fea0 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68  d and possibly h
1feb0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  armful..**.** ^T
1fec0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1fed0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1fee0 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f  lloc(), sqlite3_
1fef0 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  realloc(),.** sq
1ff00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1ff10 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
1ff20 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20  alloc64().** is 
1ff30 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
1ff40 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
1ff50 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
1ff60 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
1ff70 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
1ff80 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
1ff90 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
1ffa0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
1ffb0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
1ffc0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
1ffd0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
1ffe0 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
1fff0 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
20000 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
20010 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
20020 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
20030 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
20040 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
20050 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
20060 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
20070 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
20080 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
20090 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
200a0 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
200b0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
200c0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
200d0 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
200e0 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
200f0 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
20100 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
20110 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
20120 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
20130 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
20140 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
20150 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
20160 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
20170 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
20180 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
20190 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
201a0 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
201b0 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
201c0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
201d0 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
201e0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
201f0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
20200 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
20210 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
20220 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
20230 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
20240 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
20250 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
20260 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
20270 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
20280 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
20290 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
202a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
202b0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
202c0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
202d0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
202e0 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
202f0 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
20300 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
20310 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
20320 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
20330 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
20340 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
20350 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
20360 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
20370 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
20380 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
20390 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
203a0 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
203b0 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
203c0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
203d0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
203e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
203f0 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
20400 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
20410 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
20420 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
20430 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a  _uint64);.void *
20440 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20450 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
20460 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
20470 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69  oc64(void*, sqli
20480 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
20490 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
204a0 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75  oid*);.sqlite3_u
204b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73  int64 sqlite3_ms
204c0 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ize(void*);../*.
204d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
204e0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
204f0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
20500 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
20510 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
20520 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
20530 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
20540 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
20550 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
20560 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
20570 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
20580 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
20590 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
205a0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
205b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
205c0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
205d0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
205e0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
205f0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
20600 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
20610 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
20620 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
20630 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
20640 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
20650 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
20660 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20670 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
20680 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
20690 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
206a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
206b0 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
206c0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
206d0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
206e0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
206f0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
20700 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20710 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
20720 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20730 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
20740 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
20750 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
20760 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
20770 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
20780 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
20790 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
207a0 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
207b0 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
207c0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
207d0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
207e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
207f0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
20800 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
20810 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
20820 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
20830 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
20840 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20850 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
20860 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
20870 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
20880 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20890 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
208a0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
208b0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
208c0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
208d0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
208e0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
208f0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
20900 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
20910 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
20920 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
20930 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
20940 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20950 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
20960 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
20970 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
20980 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
20990 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
209a0 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
209b0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
209c0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
209d0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
209e0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
209f0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
20a00 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
20a10 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
20a20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
20a30 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
20a40 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
20a50 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
20a60 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
20a70 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
20a80 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
20a90 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
20aa0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
20ab0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
20ac0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
20ad0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
20ae0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
20af0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
20b00 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
20b10 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
20b20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
20b30 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
20b40 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
20b50 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65  uffer P..** ^The
20b60 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e   P parameter can
20b70 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
20b80 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
20b90 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e  is routine has n
20ba0 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73  ot been previous
20bb0 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20  ly called or if 
20bc0 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20  the previous.** 
20bd0 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20  call had N less 
20be0 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55  than one or a NU
20bf0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50  LL pointer for P
20c00 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20  , then the PRNG 
20c10 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69  is.** seeded usi
20c20 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
20c30 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  tained from the 
20c40 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
20c50 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66  od of.** the def
20c60 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
20c70 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49  s] object..** ^I
20c80 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
20c90 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
20ca0 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20  ine had an N of 
20cb0 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a  1 or more and a.
20cc0 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68  ** non-NULL P th
20cd0 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  en the pseudo-ra
20ce0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
20cf0 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
20d00 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
20d10 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
20d20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
20d30 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
20d40 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
20d50 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
20d60 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
20d70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20d80 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
20d90 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
20da0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
20db0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59  : sqlite3.** KEY
20dc0 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a  WORDS: {authoriz
20dd0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a  er callback}.**.
20de0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
20df0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
20e00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20e10 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
20e20 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
20e30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
20e40 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
20e50 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
20e60 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
20e70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20e80 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
20e90 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
20ea0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
20eb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20ec0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
20ed0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
20ee0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
20ef0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20f00 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v3()], [sqlite3_
20f10 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73  prepare16()], [s
20f20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20f30 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  _v2()],.** and [
20f40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20f50 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v3()].  ^At va
20f60 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
20f70 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
20f80 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
20f90 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
20fa0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
20fb0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
20fc0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
20fd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20fe0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
20ff0 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
21000 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
21010 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
21020 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
21030 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
21040 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
21050 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
21060 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
21070 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
21080 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
21090 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
210a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
210b0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
210c0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
210d0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
210e0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
210f0 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
21100 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
21110 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
21120 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
21130 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
21140 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
21150 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
21160 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
21170 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
21180 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
21190 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
211a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
211b0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
211c0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
211d0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
211e0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
211f0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
21200 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
21210 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
21220 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
21230 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
21240 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
21250 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
21260 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
21270 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
21280 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
21290 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
212a0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
212b0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
212c0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
212d0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
212e0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
212f0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
21300 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
21310 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
21320 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
21330 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
21340 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21350 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
21360 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
21370 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
21380 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
21390 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
213a0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
213b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
213c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
213d0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
213e0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
213f0 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
21400 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
21410 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
21420 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
21430 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
21440 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
21450 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
21460 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
21470 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e  either NULL poin
21480 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72  ters or zero-ter
21490 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a  minated strings.
214a0 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  ** that contain 
214b0 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
214c0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
214d0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
214e0 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  ized..** Applica
214f0 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79  tions must alway
21500 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f  s be prepared to
21510 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c   encounter a NUL
21520 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79  L pointer in any
21530 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64  .** of the third
21540 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78   through the six
21550 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  th parameters of
21560 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
21570 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
21580 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
21590 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
215a0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
215b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
215c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
215d0 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
215e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
215f0 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
21600 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
21610 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
21620 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
21630 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
21640 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
21650 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
21660 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
21670 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
21680 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
21690 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
216a0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
216b0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
216c0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
216d0 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
216e0 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
216f0 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65  a table..** ^Whe
21700 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66  n a table is ref
21710 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45  erenced by a [SE
21720 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c  LECT] but no col
21730 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a  umn values are.*
21740 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  * extracted from
21750 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72   that table (for
21760 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75   example in a qu
21770 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c  ery like.** "SEL
21780 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f  ECT count(*) FRO
21790 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65  M tab") then the
217a0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
217b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
217c0 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  ck.** is invoked
217d0 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74   once for that t
217e0 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75  able with a colu
217f0 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20  mn name that is 
21800 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
21810 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
21820 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
21830 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
21840 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
21850 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
21860 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
21870 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
21880 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
21890 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
218a0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
218b0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
218c0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
218d0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
218e0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
218f0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
21900 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
21910 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
21920 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
21930 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
21940 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
21950 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
21960 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
21970 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
21980 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
21990 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
219a0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
219b0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
219c0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
219d0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
219e0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
219f0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
21a00 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
21a10 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
21a20 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
21a30 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
21a40 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
21a50 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
21a60 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
21a70 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
21a80 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
21a90 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
21aa0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
21ab0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
21ac0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
21ad0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
21ae0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
21af0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
21b00 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
21b10 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
21b20 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
21b30 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
21b40 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
21b50 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
21b60 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
21b70 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
21b80 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
21b90 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
21ba0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
21bb0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
21bc0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
21bd0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
21be0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
21bf0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21c00 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
21c10 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
21c20 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
21c30 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
21c40 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
21c50 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
21c60 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
21c70 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
21c80 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
21c90 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
21ca0 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
21cb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
21cc0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
21cd0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
21ce0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
21cf0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
21d00 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
21d10 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
21d20 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
21d30 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
21d40 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
21d50 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
21d60 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
21d70 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
21d80 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21d90 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
21da0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
21db0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
21dc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21dd0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
21de0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21df0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
21e00 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
21e10 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
21e20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21e30 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
21e40 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
21e50 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
21e60 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
21e70 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
21e80 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
21e90 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
21ea0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
21eb0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
21ec0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
21ed0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
21ee0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
21ef0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
21f00 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
21f10 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
21f20 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
21f30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
21f40 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
21f50 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
21f60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21f70 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
21f80 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
21f90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21fa0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
21fb0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
21fc0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
21fd0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
21fe0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
21ff0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
22000 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
22010 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
22020 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
22030 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
22040 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
22050 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
22060 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
22070 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
22080 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
22090 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
220a0 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
220b0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
220c0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
220d0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
220e0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
220f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
22100 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
22110 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
22120 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
22130 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
22140 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
22150 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
22160 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
22170 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
22180 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
22190 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
221a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
221b0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
221c0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
221d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
221e0 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
221f0 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
22200 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
22210 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
22220 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
22230 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
22240 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
22250 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
22260 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
22270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
22280 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
22290 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
222a0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
222b0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
222c0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
222d0 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
222e0 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
222f0 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
22300 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
22310 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
22320 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
22330 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
22340 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
22350 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22360 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
22370 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
22380 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
22390 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
223a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
223b0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
223c0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
223d0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
223e0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
223f0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
22400 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
22410 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
22420 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
22430 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
22440 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
22450 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
22460 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
22470 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
22480 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
22490 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
224a0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
224b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
224c0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
224d0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
224e0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
224f0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
22500 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
22510 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
22520 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
22530 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
22540 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22550 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
22560 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
22570 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
22580 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
22590 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
225a0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
225b0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
225c0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
225d0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
225e0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
225f0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
22600 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
22610 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
22620 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
22630 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
22640 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
22650 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
22660 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
22670 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
22680 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
22690 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
226a0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
226b0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
226c0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
226d0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
226e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
226f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22700 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
22710 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
22720 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
22730 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
22740 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
22750 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
22760 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
22770 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
22780 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
22790 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
227a0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
227b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
227c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
227d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
227e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
227f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
22800 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22810 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
22820 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
22830 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
22840 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22850 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22860 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
22870 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
22880 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22890 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
228a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
228b0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
228c0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
228d0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
228e0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
228f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22900 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
22910 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22920 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22930 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22940 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22950 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
22960 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22970 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22980 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22990 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
229a0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
229b0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
229c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
229d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
229e0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
229f0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
22a00 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
22a10 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22a20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22a30 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
22a40 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
22a50 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22a60 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22a70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22a80 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
22a90 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
22aa0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22ab0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22ac0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22ad0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
22ae0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
22af0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22b00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22b10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22b20 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
22b30 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
22b40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22b50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22b60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22b70 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
22b80 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
22b90 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22ba0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22bb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22bc0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
22bd0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
22be0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22bf0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22c00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22c10 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
22c20 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
22c30 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
22c40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22c60 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
22c70 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
22c80 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
22c90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22ca0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22cb0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
22cc0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
22cd0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
22ce0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22cf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22d00 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
22d10 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
22d20 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
22d30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22d40 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
22d50 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
22d60 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
22d70 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22d80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22d90 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
22da0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
22db0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
22dc0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
22dd0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
22de0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
22df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
22e00 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22e10 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
22e20 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22e30 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
22e40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
22e50 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
22e60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22e70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22e80 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
22e90 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
22ea0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
22eb0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22ec0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22ed0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
22ee0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
22ef0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22f00 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
22f10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22f20 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
22f30 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
22f40 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
22f50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22f60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22f70 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
22f80 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
22f90 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
22fa0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22fb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22fc0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
22fd0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
22fe0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
22ff0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23010 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
23020 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
23030 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
23040 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23050 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23060 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
23070 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
23080 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
23090 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
230a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
230b0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
230c0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
230d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
230e0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
230f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23100 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
23110 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
23120 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
23130 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
23140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
23150 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
23160 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
23170 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
23180 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
23190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
231a0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
231b0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
231c0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
231d0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
231e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
231f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23200 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
23210 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
23220 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
23230 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
23240 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
23250 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
23260 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
23270 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
23280 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
23290 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
232a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
232b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
232c0 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65  es are deprecate
232d0 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  d. Use the [sqli
232e0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
232f0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73  interface.** ins
23300 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74  tead of the rout
23310 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68  ines described h
23320 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ere..**.** These
23330 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
23340 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
23350 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
23360 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
23370 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
23380 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
23390 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
233a0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
233b0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
233c0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
233d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
233e0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
233f0 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
23400 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
23410 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
23420 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
23430 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
23440 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
23450 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
23460 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
23470 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
23480 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
23490 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
234a0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
234b0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
234c0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
234d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
234e0 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
234f0 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
23500 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
23510 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
23520 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
23530 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
23540 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
23550 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
23560 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
23570 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
23580 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
23590 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
235a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
235b0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
235c0 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
235d0 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
235e0 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
235f0 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
23600 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
23610 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
23620 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
23630 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
23640 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
23650 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
23660 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
23670 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
23680 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
23690 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
236a0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
236b0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
236c0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
236d0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
236e0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
236f0 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
23700 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
23710 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
23720 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
23730 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
23740 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
23750 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
23760 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
23770 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
23780 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
23790 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
237a0 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
237b0 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
237c0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
237d0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
237e0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
237f0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
23800 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
23810 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
23820 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
23830 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
23840 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23850 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
23860 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
23870 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
23880 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
23890 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
238a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
238b0 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  */.SQLITE_DEPREC
238c0 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
238d0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
238e0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61  *,.   void(*xTra
238f0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
23900 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
23910 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
23920 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
23930 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
23940 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
23950 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
23960 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
23970 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
23980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23990 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74   SQL Trace Event
239a0 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
239b0 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45  DS: SQLITE_TRACE
239c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
239d0 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20  stants identify 
239e0 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74  classes of event
239f0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f  s that can be mo
23a00 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67  nitored.** using
23a10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
23a20 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e  ace_v2()] tracin
23a30 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68  g logic.  The th
23a40 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
23a50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
23a60 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52  e_v2()] is an OR
23a70 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  -ed combination 
23a80 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  of one or more o
23a90 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
23aa0 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e  ng constants.  ^
23ab0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
23ac0 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
23ad0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f  callback.** is o
23ae0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
23af0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a  ing constants..*
23b00 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67  *.** New tracing
23b10 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
23b20 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
23b30 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
23b40 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
23b50 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67  ack has four arg
23b60 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63  uments: xCallbac
23b70 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
23b80 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
23b90 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74  s one of the int
23ba0 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20  eger type codes 
23bb0 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43  above..** ^The C
23bc0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63   argument is a c
23bd0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
23be0 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  xt pointer passe
23bf0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
23c00 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
23c10 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
23c20 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50  _v2()]..** The P
23c30 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
23c40 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
23c50 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
23c60 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
23c70 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
23c80 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64  _TRACE_STMT]] <d
23c90 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  t>SQLITE_TRACE_S
23ca0 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TMT</dt>.** <dd>
23cb0 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
23cc0 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69  _STMT callback i
23cd0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
23ce0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
23cf0 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67  ent.** first beg
23d00 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20  ins running and 
23d10 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65  possibly at othe
23d20 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74  r times during t
23d30 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20  he.** execution 
23d40 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
23d50 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20  statement, such 
23d60 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20  as at the start 
23d70 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67  of each.** trigg
23d80 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e  er subprogram. ^
23d90 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
23da0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23db0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
23dc0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65  statement]. ^The
23dd0 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   X argument is a
23de0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
23df0 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73  ring which.** is
23e00 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20   the unexpanded 
23e10 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20  SQL text of the 
23e20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23e30 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  nt or an SQL com
23e40 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e  ment .** that in
23e50 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f  dicates the invo
23e60 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67  cation of a trig
23e70 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62  ger.  ^The callb
23e80 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a  ack can compute.
23e90 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74  ** the same text
23ea0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
23eb0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62   been returned b
23ec0 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  y the legacy [sq
23ed0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a  lite3_trace()].*
23ee0 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75  * interface by u
23ef0 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d  sing the X argum
23f00 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e  ent when X begin
23f10 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20  s with "--" and 
23f20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c  invoking.** [sql
23f30 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
23f40 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e  l(P)] otherwise.
23f50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23f60 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20  TRACE_PROFILE]] 
23f70 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
23f80 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a  _PROFILE</dt>.**
23f90 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
23fa0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
23fb0 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20  llback provides 
23fc0 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68  approximately th
23fd0 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d  e same.** inform
23fe0 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76  ation as is prov
23ff0 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ided by the [sql
24000 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20  ite3_profile()] 
24010 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  callback..** ^Th
24020 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
24030 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
24040 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24050 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
24060 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e   X argument poin
24070 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69  ts to a 64-bit i
24080 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
24090 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66  the estimated of
240a0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
240b0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61  f nanosecond tha
240c0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
240d0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
240e0 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51   run..** ^The SQ
240f0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
24100 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  LE callback is i
24110 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
24120 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
24130 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  es..**.** [[SQLI
24140 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c  TE_TRACE_ROW]] <
24150 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
24160 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ROW</dt>.** <dd>
24170 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
24180 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73  _ROW callback is
24190 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
241a0 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  r a prepared.** 
241b0 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61  statement genera
241c0 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77  tes a single row
241d0 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a   of result.  .**
241e0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
241f0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
24200 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24210 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
24220 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
24230 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  is unused..**.**
24240 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
24250 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CLOSE]] <dt>SQLI
24260 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f  TE_TRACE_CLOSE</
24270 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
24280 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
24290 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
242a0 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74  voked when a dat
242b0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
242c0 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e  ion closes..** ^
242d0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
242e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
242f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
24300 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a  nection] object.
24310 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67  ** and the X arg
24320 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
24330 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
24340 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
24350 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30  E_STMT       0x0
24360 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
24370 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20  _TRACE_PROFILE  
24380 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53    0x02.#define S
24390 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
243a0 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66         0x04.#def
243b0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
243c0 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38  _CLOSE      0x08
243d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
243e0 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b  : SQL Trace Hook
243f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
24400 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
24410 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24420 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,M,X,P) interfa
24430 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74  ce registers a t
24440 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
24450 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69   function X agai
24460 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f  nst [database co
24470 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69  nnection] D, usi
24480 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b  ng property mask
24490 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78   M.** and contex
244a0 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49  t pointer P.  ^I
244b0 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b  f the X callback
244c0 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69   is.** NULL or i
244d0 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20  f the M mask is 
244e0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69  zero, then traci
244f0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  ng is disabled. 
24500 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65   The.** M argume
24510 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
24520 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63   bitwise OR-ed c
24530 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
24540 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53   zero or more [S
24550 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e  QLITE_TRACE] con
24560 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45  stants..**.** ^E
24570 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  ach call to eith
24580 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  er sqlite3_trace
24590 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
245a0 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64  ace_v2() overrid
245b0 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29  es .** (cancels)
245c0 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73   any prior calls
245d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63   to sqlite3_trac
245e0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
245f0 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  race_v2()..**.**
24600 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b   ^The X callback
24610 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
24620 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20  ever any of the 
24630 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65  events identifie
24640 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20  d by .** mask M 
24650 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74  occur.  ^The int
24660 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75  eger return valu
24670 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62  e from the callb
24680 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ack is currently
24690 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f  .** ignored, tho
246a0 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61  ugh this may cha
246b0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65  nge in future re
246c0 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63  leases.  Callbac
246d0 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  k.** implementat
246e0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75  ions should retu
246f0 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72  rn zero to ensur
24700 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69  e future compati
24710 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
24720 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
24730 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
24740 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20  four arguments: 
24750 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58  callback(T,C,P,X
24760 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67  )..** ^The T arg
24770 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
24780 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  the [SQLITE_TRAC
24790 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  E].** constants 
247a0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20  to indicate why 
247b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73  the callback was
247c0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
247d0 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
247e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
247f0 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  ntext pointer..*
24800 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72  * The P and X ar
24810 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e  guments are poin
24820 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69  ters whose meani
24830 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e  ngs depend on T.
24840 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24850 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e  e3_trace_v2() in
24860 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
24870 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74  ded to replace t
24880 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
24890 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
248a0 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73  _trace()] and [s
248b0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
248c0 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68  ], both of which
248d0 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74  .** are deprecat
248e0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
248f0 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73  e3_trace_v2(.  s
24900 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67  qlite3*,.  unsig
24910 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74  ned uMask,.  int
24920 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73  (*xCallback)(uns
24930 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64  igned,void*,void
24940 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  *,void*),.  void
24950 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   *pCtx.);../*.**
24960 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
24970 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
24980 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
24990 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
249a0 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
249b0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
249c0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
249d0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
249e0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
249f0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
24a00 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
24a10 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
24a20 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
24a30 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
24a40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
24a50 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
24a60 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
24a70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24a80 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
24a90 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
24aa0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
24ab0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
24ac0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
24ad0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
24ae0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
24af0 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
24b00 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
24b10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
24b20 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
24b30 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
24b40 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
24b50 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e  he approximate n
24b60 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
24b70 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
24b80 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
24b90 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
24ba0 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
24bb0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
24bc0 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
24bd0 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65   X.  ^If N is le
24be0 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e  ss than one then
24bf0 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a   the progress.**
24c00 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61   handler is disa
24c10 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  bled..**.** ^Onl
24c20 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
24c30 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
24c40 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
24c50 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
24c60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24c70 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
24c80 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
24c90 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
24ca0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
24cb0 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
24cc0 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
24cd0 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
24ce0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
24cf0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
24d00 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
24d10 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
24d20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
24d30 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
24d40 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
24d50 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
24d60 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
24d70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
24d80 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
24d90 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
24da0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
24db0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
24dc0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
24dd0 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
24de0 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
24df0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
24e00 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
24e10 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
24e20 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
24e30 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
24e40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
24e50 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
24e60 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
24e70 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
24e80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24e90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
24ea0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
24eb0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
24ec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24ed0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
24ee0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
24ef0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
24f00 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
24f10 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
24f20 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
24f30 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
24f40 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
24f50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
24f60 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
24f70 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
24f80 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
24f90 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
24fa0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
24fb0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
24fc0 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
24fd0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
24fe0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
24ff0 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
25000 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
25010 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
25020 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
25030 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
25040 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25050 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
25060 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
25070 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
25080 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
25090 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
250a0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
250b0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
250c0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
250d0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
250e0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
250f0 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
25100 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
25110 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
25120 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
25130 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
25140 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
25150 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
25160 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
25170 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
25180 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
25190 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
251a0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
251b0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
251c0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
251d0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
251e0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
251f0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
25200 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
25210 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
25220 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
25230 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
25240 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
25250 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
25260 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
25270 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
25280 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
25290 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
252a0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
252b0 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
252c0 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
252d0 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
252e0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
252f0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
25300 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
25310 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
25320 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
25330 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
25340 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
25350 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
25360 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
25370 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
25380 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
25390 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
253a0 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
253b0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
253c0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
253d0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
253e0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
253f0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
25400 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
25410 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
25420 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
25430 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
25440 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
25450 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
25460 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
25470 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
25480 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
25490 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
254a0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
254b0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
254c0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
254d0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
254e0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
254f0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
25500 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
25510 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
25520 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
25530 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
25540 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
25550 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
25560 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
25570 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
25580 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
25590 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
255a0 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
255b0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
255c0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
255d0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
255e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
255f0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
25600 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
25610 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
25620 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
25630 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
25640 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
25650 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
25660 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
25670 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
25680 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
25690 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
256a0 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
256b0 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
256c0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
256d0 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
256e0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
256f0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
25700 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
25710 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
25720 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
25730 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25740 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
25750 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
25760 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
25770 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
25780 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
25790 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
257a0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
257b0 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
257c0 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
257d0 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
257e0 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
257f0 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
25800 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
25810 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
25820 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
25830 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
25840 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
25850 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
25860 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
25870 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
25880 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
25890 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
258a0 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
258b0 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
258c0 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
258d0 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
258e0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
258f0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
25900 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
25910 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
25920 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
25930 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25940 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
25950 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
25960 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
25970 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
25980 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
25990 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
259a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
259b0 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
259c0 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
259d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
259e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
259f0 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
25a00 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
25a10 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
25a20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25a30 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
25a40 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
25a50 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
25a60 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
25a70 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
25a80 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
25a90 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
25aa0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
25ab0 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
25ac0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
25ad0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
25ae0 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
25af0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25b00 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
25b10 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
25b20 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
25b30 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
25b40 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
25b50 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
25b60 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
25b70 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
25b80 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
25b90 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25ba0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
25bb0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
25bc0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
25bd0 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
25be0 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
25bf0 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
25c00 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
25c10 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
25c20 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
25c30 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
25c40 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
25c50 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
25c60 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
25c70 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
25c80 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
25c90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
25ca0 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
25cb0 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
25cc0 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
25cd0 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
25ce0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
25cf0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
25d00 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25d10 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
25d20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
25d30 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
25d40 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
25d50 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
25d60 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
25d70 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
25d80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
25d90 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
25da0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25db0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
25dc0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
25dd0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
25de0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
25df0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
25e00 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
25e10 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
25e20 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
25e30 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
25e40 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
25e50 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
25e60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
25e70 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
25e80 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
25e90 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
25ea0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25eb0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
25ec0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
25ed0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
25ee0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
25ef0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
25f00 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
25f10 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
25f20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
25f30 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
25f40 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
25f50 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
25f60 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
25f70 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
25f80 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
25f90 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
25fa0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
25fb0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
25fc0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
25fd0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
25fe0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
25ff0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
26000 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
26010 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
26020 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
26030 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
26040 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
26050 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
26060 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
26070 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
26080 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
26090 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
260a0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
260b0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
260c0 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
260d0 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
260e0 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
260f0 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
26100 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
26110 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
26120 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
26130 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
26140 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
26150 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
26160 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
26170 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
26180 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
26190 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
261a0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
261b0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
261c0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
261d0 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 74 68  ** set in the th
261e0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
261f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26200 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
26210 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
26220 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
26230 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
26240 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
26250 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
26260 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
26270 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
26280 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
26290 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
262a0 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  on..** URI filen
262b0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
262c0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
262d0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
262e0 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
262f0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
26300 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
26310 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
26320 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
26330 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
26340 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
26350 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
26360 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
26370 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
26380 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
26390 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
263a0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
263b0 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
263c0 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
263d0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
263e0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
263f0 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
26400 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
26410 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
26420 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
26430 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
26440 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
26450 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
26460 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
26470 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
26480 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
26490 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
264a0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
264b0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
264c0 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
264d0 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
264e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
264f0 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
26500 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
26510 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
26520 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
26530 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
26540 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
26550 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
26560 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
26570 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
26580 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
26590 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
265a0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
265b0 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
265c0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
265d0 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
265e0 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
265f0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
26600 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
26610 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
26620 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
26630 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
26640 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
26650 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
26660 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
26670 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
26680 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
26690 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
266a0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
266b0 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
266c0 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
266d0 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
266e0 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
266f0 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
26700 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
26710 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
26720 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
26730 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
26740 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
26750 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
26760 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
26770 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
26780 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
26790 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
267a0 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
267b0 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
267c0 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
267d0 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
267e0 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
267f0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
26800 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
26810 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
26820 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
26830 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
26840 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
26850 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
26860 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
26870 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
26880 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
26890 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
268a0 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
268b0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
268c0 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
268d0 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
268e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
268f0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
26900 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
26910 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
26920 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
26930 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
26940 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
26950 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
26960 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
26970 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
26980 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
26990 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
269a0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
269b0 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
269c0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
269d0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
269e0 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
269f0 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
26a00 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
26a10 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
26a20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
26a30 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
26a40 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
26a50 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
26a60 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
26a70 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
26a80 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
26a90 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
26aa0 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
26ab0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
26ac0 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
26ad0 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
26ae0 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
26af0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
26b00 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
26b10 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
26b20 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
26b30 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
26b40 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
26b50 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
26b60 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
26b70 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
26b80 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
26b90 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
26ba0 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
26bb0 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
26bc0 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
26bd0 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
26be0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
26bf0 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
26c00 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
26c10 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
26c20 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
26c30 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
26c40 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
26c50 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
26c60 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
26c70 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
26c80 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
26c90 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
26ca0 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
26cb0 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
26cc0 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
26cd0 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
26ce0 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
26cf0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
26d00 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
26d10 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
26d20 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
26d30 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
26d40 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
26d50 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
26d60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
26d70 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
26d80 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
26d90 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
26da0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
26db0 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
26dc0 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
26dd0 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
26de0 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
26df0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
26e00 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
26e10 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
26e20 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
26e30 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
26e40 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
26e50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26e60 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
26e70 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
26e80 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
26e90 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
26ea0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
26eb0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
26ec0 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
26ed0 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
26ee0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
26ef0 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
26f00 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
26f10 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
26f20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
26f30 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
26f40 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
26f50 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
26f60 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
26f70 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
26f80 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
26f90 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
26fa0 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
26fb0 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
26fc0 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
26fd0 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
26fe0 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
26ff0 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
27000 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
27010 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
27020 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
27030 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
27040 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
27050 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
27060 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
27070 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
27080 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
27090 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
270a0 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
270b0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
270c0 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
270d0 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
270e0 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
270f0 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
27100 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
27110 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
27120 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
27130 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
27140 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
27150 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
27160 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
27170 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
27180 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
27190 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
271a0 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
271b0 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
271c0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
271d0 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
271e0 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
271f0 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
27200 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
27210 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
27220 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
27230 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
27240 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
27250 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
27260 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
27270 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
27280 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
27290 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
272a0 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
272b0 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
272c0 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
272d0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
272e0 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
272f0 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
27300 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
27310 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
27320 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
27330 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
27340 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
27350 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
27360 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
27370 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
27380 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
27390 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
273a0 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
273b0 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
273c0 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
273d0 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
273e0 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
273f0 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
27400 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
27410 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
27420 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
27430 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
27440 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
27450 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
27460 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
27470 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
27480 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
27490 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
274a0 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
274b0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
274c0 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
274d0 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
274e0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
274f0 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
27500 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
27510 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
27520 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
27530 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
27540 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
27550 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
27560 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
27570 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
27580 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
27590 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
275a0 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
275b0 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
275c0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
275d0 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
275e0 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
275f0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
27600 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
27610 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
27620 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
27630 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
27640 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
27650 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
27660 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
27670 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
27680 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
27690 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
276a0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
276b0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
276c0 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
276d0 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
276e0 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
276f0 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
27700 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
27710 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
27720 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
27730 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
27740 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
27750 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
27760 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
27770 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
27780 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
27790 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
277a0 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
277b0 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
277c0 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
277d0 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
277e0 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
277f0 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
27800 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
27810 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
27820 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
27830 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
27840 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
27850 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
27860 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
27870 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
27880 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
27890 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
278a0 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
278b0 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
278c0 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
278d0 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
278e0 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
278f0 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
27900 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
27910 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
27920 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
27930 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
27940 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
27950 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
27960 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
27970 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
27980 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
27990 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
279a0 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
279b0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
279c0 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
279d0 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
279e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
279f0 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
27a00 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
27a10 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
27a20 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
27a30 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
27a40 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
27a50 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
27a60 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
27a70 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
27a80 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
27a90 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
27aa0 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
27ab0 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
27ac0 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
27ad0 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
27ae0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
27af0 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
27b00 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
27b10 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
27b20 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
27b30 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
27b40 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
27b50 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
27b60 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
27b70 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
27b80 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
27b90 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
27ba0 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
27bb0 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
27bc0 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
27bd0 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
27be0 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
27bf0 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
27c00 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
27c10 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
27c20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
27c30 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
27c40 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
27c50 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
27c60 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
27c70 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
27c80 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
27c90 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
27ca0 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
27cb0 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
27cc0 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
27cd0 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
27ce0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
27cf0 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
27d00 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
27d10 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
27d20 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
27d30 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
27d40 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
27d50 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
27d60 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
27d70 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
27d80 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
27d90 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
27da0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
27db0 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
27dc0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
27dd0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
27de0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
27df0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
27e00 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
27e10 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
27e20 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
27e30 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
27e40 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
27e50 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
27e60 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
27e70 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
27e80 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
27e90 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
27ea0 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
27eb0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
27ec0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
27ed0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
27ee0 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
27ef0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
27f00 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
27f10 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
27f20 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
27f30 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
27f40 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
27f50 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
27f60 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
27f70 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
27f80 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
27f90 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
27fa0 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
27fb0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
27fc0 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
27fd0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
27fe0 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
27ff0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
28000 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
28010 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
28020 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
28030 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
28040 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
28050 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
28060 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
28070 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
28080 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
28090 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
280a0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
280b0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
280c0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
280d0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
280e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
280f0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
28100 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
28110 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
28120 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
28130 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
28140 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
28150 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
28160 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
28170 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
28180 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
28190 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
281a0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
281b0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
281c0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
281d0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
281e0 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
281f0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
28200 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
28210 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
28220 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
28230 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
28240 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
28250 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
28260 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
28270 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
28280 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
28290 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
282a0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
282b0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
282c0 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
282d0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
282e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
282f0 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
28300 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
28310 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
28320 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
28330 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
28340 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
28350 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
28360 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
28370 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
28380 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
28390 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
283a0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
283b0 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
283c0 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
283d0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
283e0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
283f0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
28400 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
28410 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
28420 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
28430 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
28440 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
28450 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
28460 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
28470 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
28480 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
28490 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
284a0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
284b0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
284c0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
284d0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
284e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
284f0 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
28500 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
28510 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
28520 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
28530 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
28540 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
28550 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
28560 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
28570 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
28580 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
28590 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
285a0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
285b0 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
285c0 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
285d0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
285e0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
285f0 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
28600 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
28610 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
28620 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
28630 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
28640 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
28650 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
28660 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
28670 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
28680 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
28690 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
286a0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
286b0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
286c0 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
286d0 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
286e0 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
286f0 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
28700 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
28710 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
28720 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
28730 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
28740 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
28750 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
28760 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
28770 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
28780 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
28790 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
287a0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
287b0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
287c0 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
287d0 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
287e0 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
287f0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
28800 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
28810 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
28820 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
28830 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
28840 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
28850 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
28860 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
28870 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
28880 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
28890 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
288a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
288b0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
288c0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
288d0 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
288e0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
288f0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
28900 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
28910 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
28920 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
28930 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
28940 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
28950 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
28960 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
28970 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
28980 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
28990 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
289a0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
289b0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
289c0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
289d0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
289e0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
289f0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
28a00 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
28a10 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
28a20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69  .int sqlite3_uri
28a30 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
28a40 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
28a50 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
28a60 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73  int bDefault);.s
28a70 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
28a80 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
28a90 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
28aa0 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
28ab0 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
28ac0 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
28ad0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
28ae0 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ges.** METHOD: s
28af0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66  qlite3.**.** ^If
28b00 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
28b10 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
28b20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
28b30 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ith .** [databas
28b40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
28b50 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  failed, then the
28b60 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
28b70 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  (D) interface.**
28b80 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
28b90 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
28ba0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
28bb0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
28bc0 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c   that.** API cal
28bd0 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73  l..** If the mos
28be0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
28bf0 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c  l was successful
28c00 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
28c10 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
28c20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
28c30 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  ) is undefined..
28c40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28c50 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
28c60 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
28c70 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
28c80 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
28c90 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
28ca0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
28cb0 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
28cc0 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
28cd0 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
28ce0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
28cf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
28d00 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
28d10 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
28d20 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
28d30 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
28d40 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
28d50 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
28d60 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
28d70 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
28d80 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
28d90 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
28da0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
28db0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
28dc0 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
28dd0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
28de0 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
28df0 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
28e00 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
28e10 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
28e20 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
28e30 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
28e40 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
28e50 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
28e60 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
28e70 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
28e80 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
28e90 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
28ea0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
28eb0 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
28ec0 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
28ed0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
28ee0 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
28ef0 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
28f00 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
28f10 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
28f20 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
28f30 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
28f40 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
28f50 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
28f60 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
28f70 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
28f80 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
28f90 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
28fa0 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
28fb0 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
28fc0 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
28fd0 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
28fe0 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
28ff0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
29000 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
29010 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
29020 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
29030 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
29040 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
29050 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
29060 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
29070 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
29080 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
29090 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
290a0 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
290b0 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
290c0 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
290d0 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
290e0 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
290f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29100 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
29110 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
29120 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
29130 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
29140 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
29150 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
29160 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
29170 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
29180 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
29190 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
291a0 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
291b0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
291c0 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
291d0 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
291e0 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
291f0 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
29200 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
29210 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
29220 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
29230 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
29240 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
29250 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
29260 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
29270 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
29280 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
29290 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
292a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
292b0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
292c0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
292d0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
292e0 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
292f0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
29300 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
29310 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
29320 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
29330 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  3*);.const char 
29340 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
29350 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
29360 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20  I3REF: Prepared 
29370 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
29380 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
29390 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
293a0 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
293b0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
293c0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
293d0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
293e0 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
293f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
29400 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  .** has been com
29410 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72  piled into binar
29420 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65  y form and is re
29430 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61  ady to be evalua
29440 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b  ted..**.** Think
29450 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61   of each SQL sta
29460 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61  tement as a sepa
29470 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72  rate computer pr
29480 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f  ogram.  The.** o
29490 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
294a0 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e   is source code.
294b0 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61    A prepared sta
294c0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a  tement object .*
294d0 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65  * is the compile
294e0 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20  d object code.  
294f0 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20  All SQL must be 
29500 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
29510 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
29520 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74  tement before it
29530 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a   can be run..**.
29540 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c  ** The life-cycl
29550 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20  e of a prepared 
29560 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
29570 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69   usually goes li
29580 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
29590 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
295a0 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20  te the prepared 
295b0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
295c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
295d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a  prepare_v2()]..*
295e0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
295f0 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  es to [parameter
29600 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
29610 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
29620 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
29630 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
29640 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
29650 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29660 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
29670 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
29680 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
29690 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
296a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
296b0 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
296c0 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
296d0 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
296e0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
296f0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
29700 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
29710 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
29720 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
29730 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
29740 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
29750 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
29760 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
29770 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20  -time Limits.** 
29780 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
29790 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
297a0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
297b0 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
297c0 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
297d0 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
297e0 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
297f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
29800 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
29810 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
29820 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
29830 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
29840 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
29850 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
29860 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
29870 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
29880 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
29890 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
298a0 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
298b0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
298c0 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
298d0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
298e0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
298f0 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
29900 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
29910 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
29920 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
29930 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
29940 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
29950 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
29960 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
29970 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
29980 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
29990 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
299a0 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
299b0 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
299c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
299d0 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
299e0 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
299f0 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
29a00 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
29a10 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
29a20 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
29a30 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
29a40 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
29a50 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
29a60 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
29a70 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
29a80 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
29a90 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
29aa0 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
29ab0 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
29ac0 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
29ad0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
29ae0 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
29af0 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
29b00 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
29b10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29b20 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
29b30 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
29b40 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
29b50 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
29b60 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
29b70 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
29b80 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
29b90 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
29ba0 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
29bb0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
29bc0 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
29bd0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
29be0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
29bf0 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
29c00 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
29c10 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
29c20 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
29c30 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
29c40 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
29c50 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
29c60 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
29c70 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
29c80 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
29c90 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
29ca0 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
29cb0 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
29cc0 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
29cd0 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
29ce0 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
29cf0 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
29d00 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
29d10 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
29d20 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
29d30 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
29d40 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
29d50 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
29d60 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
29d70 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
29d80 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
29d90 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
29da0 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
29db0 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
29dc0 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
29dd0 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
29de0 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
29df0 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
29e00 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
29e10 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
29e20 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
29e30 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
29e40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
29e50 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
29e60 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
29e70 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
29e80 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
29e90 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
29ea0 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
29eb0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
29ec0 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
29ed0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
29ee0 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
29ef0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
29f00 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
29f10 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
29f20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
29f30 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
29f40 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
29f50 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
29f60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
29f70 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
29f80 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
29f90 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
29fa0 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
29fb0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
29fc0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
29fd0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
29fe0 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
29ff0 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
2a000 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
2a010 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
2a020 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
2a030 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
2a040 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
2a050 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
2a060 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
2a070 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
2a080 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
2a090 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
2a0a0 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
2a0b0 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
2a0c0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
2a0d0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2a0e0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a0f0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
2a100 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a110 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
2a120 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
2a130 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
2a140 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
2a150 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a160 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
2a170 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a180 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
2a190 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a1a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
2a1b0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
2a1c0 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
2a1d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2a1e0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
2a1f0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a200 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
2a210 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a220 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
2a230 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
2a240 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
2a250 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
2a260 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2a270 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
2a280 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2a290 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
2a2a0 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
2a2b0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
2a2c0 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
2a2d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a2e0 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
2a2f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a300 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
2a310 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a320 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
2a330 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
2a340 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
2a350 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2a360 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2a370 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
2a380 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a390 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
2a3a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a3b0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2a3c0 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
2a3d0 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
2a3e0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
2a3f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a400 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
2a410 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a420 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
2a430 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a440 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
2a450 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
2a460 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
2a470 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
2a480 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
2a490 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  L statement.  If
2a4a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a4b0 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68  e_v2()] or.** th
2a4c0 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69  e equivalent tri
2a4d0 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73  es to allocate s
2a4e0 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68  pace for more th
2a4f0 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63  an this many opc
2a500 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e  odes.** in a sin
2a510 67 6c 65 20 70 72 65 70 61 72 65 64 20 73 74 61  gle prepared sta
2a520 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54  tement, an SQLIT
2a530 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73  E_NOMEM error is
2a540 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
2a550 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2a560 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2a570 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
2a580 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2a590 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
2a5a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2a5b0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2a5c0 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
2a5d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a5e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2a5f0 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
2a600 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
2a610 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
2a620 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2a630 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
2a640 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2a650 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
2a660 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a670 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2a680 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
2a690 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2a6a0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2a6b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2a6c0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
2a6d0 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
2a6e0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
2a6f0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
2a700 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
2a710 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a720 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2a730 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
2a740 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2a750 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2a760 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
2a770 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
2a780 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
2a790 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
2a7a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
2a7b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2a7c0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
2a7d0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
2a7e0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2a7f0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
2a800 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
2a810 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
2a820 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
2a830 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2a840 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2a850 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c  ER_THREADS]] ^(<
2a860 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a870 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f  WORKER_THREADS</
2a880 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a890 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2a8a0 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65   auxiliary worke
2a8b0 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61  r threads that a
2a8c0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70   single.** [prep
2a8d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a8e0 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29  may start.</dd>)
2a8f0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
2a900 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a910 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
2a920 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
2a930 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a940 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
2a950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
2a960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a970 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
2a980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
2a990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a9a0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
2a9b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a9c0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
2a9d0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
2a9e0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
2a9f0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2aa00 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
2aa10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2aa20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
2aa30 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2aa40 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
2aa50 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
2aa60 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
2aa70 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
2aa80 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
2aa90 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
2aaa0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
2aab0 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
2aac0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2aad0 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
2aae0 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
2aaf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
2ab00 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
2ab10 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
2ab20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f   SQLITE_LIMIT_WO
2ab30 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20  RKER_THREADS    
2ab40 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a         11../*.**
2ab50 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61   CAPI3REF: Prepa
2ab60 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54  re Flags.**.** T
2ab70 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
2ab80 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c  efine various fl
2ab90 61 67 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ags that can be 
2aba0 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22  passed into.** "
2abb0 70 72 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d  prepFlags" param
2abc0 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c  eter of the [sql
2abd0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2abe0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
2abf0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2ac00 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  )] interfaces..*
2ac10 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d  *.** New flags m
2ac20 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
2ac30 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
2ac40 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
2ac50 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
2ac60 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2ac70 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ENT]] ^(<dt>SQLI
2ac80 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2ac90 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  STENT</dt>.** <d
2aca0 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45  d>The SQLITE_PRE
2acb0 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20  PARE_PERSISTENT 
2acc0 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74 20 74  flag is a hint t
2acd0 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e  o the query plan
2ace0 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ner.** that the 
2acf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ad00 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69  nt will be retai
2ad10 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74  ned for a long t
2ad20 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61  ime and.** proba
2ad30 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20  bly reused many 
2ad40 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75  times.)^ ^Withou
2ad50 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71  t this flag, [sq
2ad60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2ad70 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2ad80 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2ad90 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20  ()] assume that 
2ada0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2adb0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20  tement will .** 
2adc0 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63  be used just onc
2add0 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66  e or at most a f
2ade0 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65  ew times and the
2adf0 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e  n destroyed usin
2ae00 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  g.** [sqlite3_fi
2ae10 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69  nalize()] relati
2ae20 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63  vely soon. The c
2ae30 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
2ae40 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e  ation acts.** on
2ae50 20 74 68 69 73 20 68 69 6e 74 20 62 79 20 61 76   this hint by av
2ae60 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f  oiding the use o
2ae70 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  f [lookaside mem
2ae80 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74  ory] so as not t
2ae90 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65  o.** deplete the
2aea0 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f   limited store o
2aeb0 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
2aec0 72 79 2e 20 46 75 74 75 72 65 20 76 65 72 73 69  ry. Future versi
2aed0 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ons of.** SQLite
2aee0 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73   may act on this
2aef0 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c   hint differentl
2af00 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  y..** </dl>.*/.#
2af10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
2af20 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2af30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
2af40 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  01../*.** CAPI3R
2af50 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
2af60 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2af70 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
2af80 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
2af90 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
2afa0 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54  sqlite3.** CONST
2afb0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
2afc0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  stmt.**.** To ex
2afd0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61  ecute an SQL sta
2afe0 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20  tement, it must 
2aff0 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
2b000 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
2b010 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
2b020 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
2b030 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20   routines.  Or, 
2b040 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
2b050 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2b060 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f  * are constructo
2b070 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  rs for the [prep
2b080 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b090 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  object..**.** Th
2b0a0 65 20 70 72 65 66 65 72 72 65 64 20 72 6f 75 74  e preferred rout
2b0b0 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73  ine to use is [s
2b0c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b0d0 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  2()].  The.** [s
2b0e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2b0f0 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c  ] interface is l
2b100 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64  egacy and should
2b110 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20   be avoided..** 
2b120 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b130 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78  _v3()] has an ex
2b140 74 72 61 20 22 70 72 65 70 46 6c 61 67 73 22 20  tra "prepFlags" 
2b150 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75  option that is u
2b160 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69  sed.** for speci
2b170 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  al purposes..**.
2b180 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  ** The use of th
2b190 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63  e UTF-8 interfac
2b1a0 65 73 20 69 73 20 70 72 65 66 65 72 72 65 64 2c  es is preferred,
2b1b0 20 61 73 20 53 51 4c 69 74 65 20 63 75 72 72 65   as SQLite curre
2b1c0 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c  ntly.** does all
2b1d0 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55   parsing using U
2b1e0 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31  TF-8.  The UTF-1
2b1f0 36 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  6 interfaces are
2b200 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20   provided.** as 
2b210 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20  a convenience.  
2b220 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72  The UTF-16 inter
2b230 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f  faces work by co
2b240 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20  nverting the.** 
2b250 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20  input text into 
2b260 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f  UTF-8, then invo
2b270 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70  king the corresp
2b280 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74  onding UTF-8 int
2b290 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
2b2a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2b2b0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
2b2c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b2d0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
2b2e0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
2b2f0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
2b300 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2b310 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2b320 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
2b330 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
2b340 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
2b350 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
2b360 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
2b370 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
2b380 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
2b390 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
2b3a0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2b3b0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
2b3c0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
2b3d0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
2b3e0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2b3f0 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  e(), sqlite3_pre
2b400 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  pare_v2(),.** an
2b410 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2b420 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v3().** interf
2b430 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
2b440 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2b450 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33  are16(), sqlite3
2b460 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c  _prepare16_v2(),
2b470 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2b480 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 75  prepare16_v3() u
2b490 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
2b4a0 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
2b4b0 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74  rgument is negat
2b4c0 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ive, then zSql i
2b4d0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
2b4e0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
2b4f0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
2b500 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65  Byte is positive
2b510 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
2b520 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
2b530 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
2b540 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69  ql.  ^If nByte i
2b550 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20  s zero, then no 
2b560 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2b570 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74  ement is generat
2b580 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
2b590 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20  ller knows that 
2b5a0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
2b5b0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
2b5c0 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74  nated, then.** t
2b5d0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20  here is a small 
2b5e0 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
2b5f0 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67  ntage to passing
2b600 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
2b610 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74  ter that.** is t
2b620 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2b630 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
2b640 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
2b650 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
2b660 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ul-terminator..*
2b670 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
2b680 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
2b690 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
2b6a0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
2b6b0 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
2b6c0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
2b6d0 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
2b6e0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
2b6f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2b700 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
2b710 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
2b720 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
2b730 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
2b740 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
2b750 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
2b760 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
2b770 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
2b780 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
2b790 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
2b7a0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2b7b0 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
2b7c0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2b7d0 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
2b7e0 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
2b7f0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
2b800 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
2b810 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
2b820 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
2b830 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
2b840 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
2b850 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
2b860 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
2b870 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
2b880 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
2b890 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
2b8a0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
2b8b0 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
2b8c0 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
2b8d0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
2b8e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
2b8f0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
2b900 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
2b910 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
2b920 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
2b930 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
2b940 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2b950 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
2b960 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2b970 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
2b980 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
2b990 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2b9a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
2b9b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b9c0 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2b9d0 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33  re_v3(), sqlite3
2b9e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c  _prepare16_v2(),
2b9f0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2ba00 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 69  prepare16_v3() i
2ba10 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
2ba20 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
2ba30 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a  l new programs..
2ba40 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74  ** The older int
2ba50 65 72 66 61 63 65 73 20 28 73 71 6c 69 74 65 33  erfaces (sqlite3
2ba60 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
2ba70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ba80 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69  ()).** are retai
2ba90 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
2baa0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
2bab0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
2bac0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
2bad0 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69  * ^In the "vX" i
2bae0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
2baf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bb00 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
2bb10 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
2bb20 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2bb30 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
2bb40 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
2bb50 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
2bb60 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
2bb70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2bb80 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
2bb90 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
2bba0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
2bbb0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
2bbc0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2bbd0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
2bbe0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
2bbf0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
2bc00 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
2bc10 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
2bc20 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
2bc30 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
2bc40 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
2bc50 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
2bc60 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
2bc70 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
2bc80 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
2bc90 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
2bca0 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
2bcb0 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
2bcc0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
2bcd0 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
2bce0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
2bcf0 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
2bd00 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
2bd10 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
2bd20 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
2bd30 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
2bd40 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
2bd50 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
2bd60 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
2bd70 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
2bd80 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
2bd90 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
2bda0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2bdb0 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
2bdc0 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
2bdd0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
2bde0 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
2bdf0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2be00 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
2be10 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
2be20 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
2be30 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
2be40 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
2be50 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
2be60 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
2be70 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
2be80 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
2be90 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
2bea0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
2beb0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
2bec0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
2bed0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
2bee0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2bef0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
2bf00 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
2bf10 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
2bf20 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
2bf30 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
2bf40 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
2bf50 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
2bf60 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
2bf70 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
2bf80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2bf90 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
2bfa0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
2bfb0 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
2bfc0 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
2bfd0 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
2bfe0 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
2bff0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
2c000 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
2c010 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
2c020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2c030 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
2c040 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
2c050 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
2c060 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
2c070 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
2c080 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
2c090 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
2c0a0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2c0b0 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
2c0c0 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
2c0d0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
2c0e0 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
2c0f0 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
2c100 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2c110 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
2c120 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
2c130 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
2c140 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
2c150 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2c160 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
2c170 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2c180 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65   <p>^sqlite3_pre
2c190 70 61 72 65 5f 76 33 28 29 20 64 69 66 66 65 72  pare_v3() differ
2c1a0 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70  s from sqlite3_p
2c1b0 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79  repare_v2() only
2c1c0 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68   in having.** th
2c1d0 65 20 65 78 74 72 61 20 70 72 65 70 46 6c 61 67  e extra prepFlag
2c1e0 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69  s parameter, whi
2c1f0 63 68 20 69 73 20 61 20 62 69 74 20 61 72 72 61  ch is a bit arra
2c200 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20  y consisting of 
2c210 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20  zero or.** more 
2c220 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50  of the [SQLITE_P
2c230 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2c240 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  T|SQLITE_PREPARE
2c250 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65  _*] flags.  ^The
2c260 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
2c270 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  are_v2() interfa
2c280 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  ce works exactly
2c290 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
2c2a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c2b0 76 33 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f  v3() with a zero
2c2c0 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d   prepFlags param
2c2d0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  eter..** </ol>.*
2c2e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
2c2f0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
2c300 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2c310 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2c320 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2c330 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2c340 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2c350 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2c360 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2c370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2c380 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2c390 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2c3a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2c3b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2c3c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2c3d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c3e0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2c3f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2c400 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2c410 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2c420 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2c430 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
2c440 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2c450 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2c460 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2c470 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2c480 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2c490 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2c4a0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2c4b0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2c4c0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2c4d0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2c4e0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2c4f0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2c500 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2c510 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2c520 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2c530 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2c540 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2c550 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2c560 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2c570 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c580 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  3(.  sqlite3 *db
2c590 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2c5a0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2c5b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c5c0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2c5d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2c5e0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2c5f0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2c600 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2c610 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2c620 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2c630 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  .  unsigned int 
2c640 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65  prepFlags, /* Ze
2c650 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54  ro or more SQLIT
2c660 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73  E_PREPARE_ flags
2c670 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2c680 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2c690 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2c6a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c6b0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2c6c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2c6d0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2c6e0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2c6f0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2c700 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
2c710 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2c720 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2c730 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c740 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2c750 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2c760 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2c770 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2c780 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2c790 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2c7a0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2c7b0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2c7c0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2c7d0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2c7e0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2c7f0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2c800 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2c810 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2c820 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2c830 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2c840 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2c850 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2c860 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2c870 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2c880 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2c890 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2c8a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2c8b0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2c8c0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2c8d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2c8e0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2c8f0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2c900 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2c910 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2c920 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2c930 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c940 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2c950 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2c960 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2c970 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2c980 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2c990 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73  repare16_v3(.  s
2c9a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2c9b0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2c9c0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2c9d0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2c9e0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2c9f0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2ca00 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2ca10 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2ca20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2ca30 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2ca40 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e  n bytes. */.  un
2ca50 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46  signed int prepF
2ca60 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72  lags, /* Zero or
2ca70 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45   more SQLITE_PRE
2ca80 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20  PARE_ flags */. 
2ca90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2caa0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2cab0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2cac0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2cad0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2cae0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2caf0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2cb00 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
2cb10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cb20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
2cb30 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48  ment SQL.** METH
2cb40 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2cb50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2cb60 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  te3_sql(P) inter
2cb70 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2cb80 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79  ointer to a copy
2cb90 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a   of the UTF-8.**
2cba0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
2cbb0 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72  o create [prepar
2cbc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20  ed statement] P 
2cbd0 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61  if P was.** crea
2cbe0 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2cbf0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2cc00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2cc10 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
2cc20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2cc30 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
2cc40 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e  prepare16_v3()].
2cc50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cc60 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2cc70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2cc80 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2cc90 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2cca0 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2ccb0 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65   SQL text of pre
2ccc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ccd0 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64  P with.** [bound
2cce0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70   parameters] exp
2ccf0 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  anded..**.** ^(F
2cd00 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2cd10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cd20 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75  ent is created u
2cd30 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20  sing the SQL.** 
2cd40 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62  text "SELECT $ab
2cd50 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70  c,:xyz" and if p
2cd60 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73  arameter $abc is
2cd70 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65   bound to intege
2cd80 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61  r 2345.** and pa
2cd90 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20  rameter :xyz is 
2cda0 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71  unbound, then sq
2cdb0 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c  lite3_sql() will
2cdc0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f   return.** the o
2cdd0 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20  riginal string, 
2cde0 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2cdf0 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65  z" but sqlite3_e
2ce00 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a  xpanded_sql().**
2ce10 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45   will return "SE
2ce20 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e  LECT 2345,NULL".
2ce30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2ce40 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2ce50 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ql() interface r
2ce60 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
2ce70 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
2ce80 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62  ry.** is availab
2ce90 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  le to hold the r
2cea0 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65  esult, or if the
2ceb0 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78   result would ex
2cec0 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20  ceed the.** the 
2ced0 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c  maximum string l
2cee0 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64  ength determined
2cef0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
2cf00 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  LIMIT_LENGTH]..*
2cf10 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
2cf20 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
2cf30 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
2cf40 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74   option limits t
2cf50 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f  he size of.** bo
2cf60 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 78  und parameter ex
2cf70 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20  pansions.  ^The 
2cf80 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41  [SQLITE_OMIT_TRA
2cf90 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
2cfa0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65  .** option cause
2cfb0 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  s sqlite3_expand
2cfc0 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61  ed_sql() to alwa
2cfd0 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  ys return NULL..
2cfe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  **.** ^The strin
2cff0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2d000 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20  lite3_sql(P) is 
2d010 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74  managed by SQLit
2d020 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f  e and is.** auto
2d030 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2d040 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  when the prepare
2d050 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66  d statement is f
2d060 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68  inalized..** ^Th
2d070 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2d080 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70  d by sqlite3_exp
2d090 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e  anded_sql(P), on
2d0a0 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
2d0b0 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20  .** is obtained 
2d0c0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2d0d0 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74  lloc()] and must
2d0e0 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20   be free by the 
2d0f0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62  application.** b
2d100 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  y passing it to 
2d110 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2d120 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2d130 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
2d140 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2d150 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
2d160 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71  _expanded_sql(sq
2d170 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2d180 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d190 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2d1a0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
2d1b0 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
2d1c0 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
2d1d0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d1e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d1f0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d200 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
2d210 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2d220 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
2d230 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
2d240 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d250 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
2d260 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
2d270 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2d280 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2d290 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2d2a0 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
2d2b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d2c0 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
2d2d0 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
2d2e0 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
2d2f0 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
2d300 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
2d310 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
2d320 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
2d330 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2d340 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
2d350 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
2d360 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
2d370 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
2d380 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
2d390 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
2d3a0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2d3b0 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
2d3c0 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
2d3d0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2d3e0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
2d3f0 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
2d400 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
2d410 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
2d420 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2d430 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
2d440 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2d450 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
2d460 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2d470 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
2d480 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
2d490 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
2d4a0 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
2d4b0 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
2d4c0 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
2d4d0 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
2d4e0 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
2d4f0 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
2d500 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
2d510 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
2d520 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
2d530 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2d540 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
2d550 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
2d560 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
2d570 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
2d580 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
2d590 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
2d5a0 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
2d5b0 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
2d5c0 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
2d5d0 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
2d5e0 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
2d5f0 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
2d600 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
2d610 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
2d620 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2d630 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2d640 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
2d650 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
2d660 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
2d670 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
2d680 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
2d690 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
2d6a0 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
2d6b0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
2d6c0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2d6d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
2d6e0 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68   on disk..** ^Th
2d6f0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2d700 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66  eadonly() interf
2d710 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2d720 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e   for [BEGIN] sin
2d730 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65  ce.** [BEGIN] me
2d740 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e  rely sets intern
2d750 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68  al flags, but th
2d760 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49  e [BEGIN|BEGIN I
2d770 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a  MMEDIATE] and.**
2d780 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58   [BEGIN|BEGIN EX
2d790 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64  CLUSIVE] command
2d7a0 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64  s do touch the d
2d7b0 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a  atabase and so.*
2d7c0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2d7d0 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e  eadonly() return
2d7e0 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73  s false for thos
2d7f0 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69  e commands..*/.i
2d800 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2d810 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
2d820 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2d830 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d840 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
2d850 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2d860 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
2d870 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2d880 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2d890 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2d8a0 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
2d8b0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2d8c0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
2d8d0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2d8e0 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
2d8f0 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
2d900 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
2d910 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
2d920 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
2d930 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f  either run to co
2d940 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e  mpletion (return
2d950 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ed.** [SQLITE_DO
2d960 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  NE] from [sqlite
2d970 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a  3_step(S)]) nor.
2d980 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
2d990 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2d9a0 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
2d9b0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2d9c0 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
2d9d0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
2d9e0 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
2d9f0 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
2da00 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
2da10 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
2da20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2da30 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
2da40 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2da50 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
2da60 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2da70 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2da80 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
2da90 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2daa0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2dab0 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
2dac0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2dad0 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
2dae0 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
2daf0 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
2db00 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
2db10 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
2db20 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
2db30 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
2db40 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
2db50 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
2db60 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
2db70 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
2db80 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
2db90 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
2dba0 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
2dbb0 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
2dbc0 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
2dbd0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2dbe0 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
2dbf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2dc00 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
2dc10 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
2dc20 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2dc30 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
2dc40 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
2dc50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2dc60 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
2dc70 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
2dc80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2dc90 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
2dca0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
2dcb0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
2dcc0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
2dcd0 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
2dce0 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
2dcf0 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
2dd00 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
2dd10 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
2dd20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2dd30 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
2dd40 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
2dd50 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
2dd60 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
2dd70 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
2dd80 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2dd90 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
2dda0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
2ddb0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
2ddc0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
2ddd0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
2dde0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ddf0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
2de00 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
2de10 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
2de20 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
2de30 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2de40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2de50 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
2de60 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
2de70 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
2de80 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
2de90 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
2dea0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
2deb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2dec0 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a  3_value.  The.**
2ded0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2dee0 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  dup()] interface
2def0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2df00 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20  construct a new 
2df10 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71  .** protected sq
2df20 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d  lite3_value from
2df30 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2df40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2df50 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
2df60 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
2df70 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
2df80 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
2df90 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
2dfa0 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
2dfb0 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
2dfc0 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
2dfd0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2dfe0 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
2dff0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
2e000 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
2e010 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2e020 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
2e030 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2e040 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
2e050 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
2e060 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
2e070 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
2e080 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
2e090 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
2e0a0 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
2e0b0 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
2e0c0 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
2e0d0 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
2e0e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2e0f0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
2e100 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2e110 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
2e120 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
2e130 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2e140 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2e150 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2e160 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e170 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
2e180 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
2e190 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
2e1a0 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
2e1b0 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
2e1c0 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
2e1d0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
2e1e0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
2e1f0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
2e200 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2e210 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2e220 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2e230 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e240 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
2e250 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
2e260 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2e270 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e280 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
2e290 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
2e2a0 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
2e2b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2e2c0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2e2d0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2e2e0 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
2e2f0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
2e300 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2e310 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2e320 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e330 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
2e340 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
2e350 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e360 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
2e370 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2e380 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
2e390 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
2e3a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2e3b0 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
2e3c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2e3d0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
2e3e0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
2e3f0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
2e400 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
2e410 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e420 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
2e430 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2e440 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  t sqlite3_value 
2e450 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
2e460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e470 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
2e480 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
2e490 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
2e4a0 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
2e4b0 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
2e4c0 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
2e4d0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
2e4e0 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
2e4f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
2e500 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2e510 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
2e520 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2e530 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
2e540 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2e550 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
2e560 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e570 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2e580 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e590 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
2e5a0 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
2e5b0 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
2e5c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2e5d0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
2e5e0 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
2e5f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2e600 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
2e610 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2e620 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
2e630 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2e640 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
2e650 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
2e660 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
2e670 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
2e680 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2e690 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2e6a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2e6b0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
2e6c0 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
2e6d0 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
2e6e0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
2e6f0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
2e700 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
2e710 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
2e720 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
2e730 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2e740 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
2e750 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
2e760 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2e770 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2e780 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e790 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
2e7a0 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
2e7b0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
2e7c0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2e7d0 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
2e7e0 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
2e7f0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
2e800 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
2e810 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
2e820 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
2e830 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
2e840 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
2e850 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
2e860 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
2e870 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
2e880 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
2e890 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
2e8a0 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
2e8b0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
2e8c0 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
2e8d0 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
2e8e0 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
2e8f0 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
2e900 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
2e910 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
2e920 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
2e930 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
2e940 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
2e950 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
2e960 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
2e970 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2e980 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2e990 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
2e9a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2e9b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2e9c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2e9d0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
2e9e0 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
2e9f0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
2ea00 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
2ea10 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
2ea20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ea30 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
2ea40 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
2ea50 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2ea60 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2ea70 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
2ea80 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
2ea90 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
2eaa0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
2eab0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2eac0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
2ead0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
2eae0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
2eaf0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
2eb00 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2eb10 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
2eb20 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
2eb30 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
2eb40 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
2eb50 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
2eb60 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
2eb70 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
2eb80 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
2eb90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2eba0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2ebb0 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
2ebc0 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
2ebd0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
2ebe0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
2ebf0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
2ec00 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
2ec10 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
2ec20 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
2ec30 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
2ec40 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
2ec50 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2ec60 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
2ec70 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
2ec80 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2ec90 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2eca0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
2ecb0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
2ecc0 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
2ecd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2ece0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2ecf0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2ed00 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
2ed10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2ed20 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
2ed30 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
2ed40 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ed50 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
2ed60 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
2ed70 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
2ed80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2ed90 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
2eda0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
2edb0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
2edc0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
2edd0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2ede0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2edf0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2ee00 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
2ee10 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
2ee20 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
2ee30 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
2ee40 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
2ee50 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2ee60 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
2ee70 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2ee80 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2ee90 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2eea0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2eeb0 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
2eec0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
2eed0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
2eee0 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
2eef0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
2ef00 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
2ef10 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
2ef20 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
2ef30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2ef40 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2ef50 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2ef60 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
2ef70 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2ef80 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
2ef90 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
2efa0 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
2efb0 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
2efc0 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
2efd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2efe0 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33  t16() or sqlite3
2eff0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74  _bind_text64() t
2f000 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61  hen.** that para
2f010 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
2f020 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
2f030 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
2f040 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
2f050 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
2f060 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
2f070 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
2f080 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
2f090 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
2f0a0 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
2f0b0 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
2f0c0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
2f0d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2f0e0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
2f0f0 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
2f100 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
2f110 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
2f120 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
2f130 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
2f140 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
2f150 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
2f160 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2f170 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
2f180 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2f190 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20  BLOB and string 
2f1a0 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63  binding interfac
2f1b0 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72  es.** is a destr
2f1c0 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
2f1d0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2f1e0 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
2f1f0 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
2f200 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2f210 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
2f220 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
2f230 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2f240 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
2f250 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
2f260 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61  l to bind API fa
2f270 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ils..** ^If the 
2f280 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
2f290 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
2f2a0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
2f2b0 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
2f2c0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
2f2d0 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
2f2e0 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
2f2f0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
2f300 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
2f310 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
2f320 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2f330 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
2f340 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
2f350 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
2f360 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
2f370 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
2f380 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
2f390 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
2f3a0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
2f3b0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2f3c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
2f3d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2f3e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2f3f0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2f400 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  () must be one o
2f410 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  f.** [SQLITE_UTF
2f420 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2f430 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
2f440 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
2f450 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20  _UTF16LE].** to 
2f460 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f  specify the enco
2f470 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74  ding of the text
2f480 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
2f490 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20  rameter.  If.** 
2f4a0 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  the sixth argume
2f4b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2f4c0 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e  nd_text64() is n
2f4d0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
2f4e0 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
2f4f0 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20  shown above, or 
2f500 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  if the text enco
2f510 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2f520 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e  t.** from the en
2f530 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
2f540 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61   by the sixth pa
2f550 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
2f560 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
2f570 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2f580 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2f590 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
2f5a0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
2f5b0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
2f5c0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
2f5d0 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
2f5e0 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
2f5f0 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
2f600 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
2f610 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
2f620 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
2f630 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
2f640 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
2f650 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
2f660 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
2f670 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
2f680 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
2f690 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
2f6a0 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
2f6b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
2f6c0 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
2f6d0 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
2f6e0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
2f6f0 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
2f700 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
2f710 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
2f720 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
2f730 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f740 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53  3_bind_pointer(S
2f750 2c 49 2c 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e  ,I,P,T,D) routin
2f760 65 20 63 61 75 73 65 73 20 74 68 65 20 49 2d 74  e causes the I-t
2f770 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a  h parameter in.*
2f780 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2f790 65 6d 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65  ement] S to have
2f7a0 20 61 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66   an SQL value of
2f7b0 20 4e 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c   NULL, but to al
2f7c0 73 6f 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61  so be.** associa
2f7d0 74 65 64 20 77 69 74 68 20 74 68 65 20 70 6f 69  ted with the poi
2f7e0 6e 74 65 72 20 50 20 6f 66 20 74 79 70 65 20 54  nter P of type T
2f7f0 2e 20 20 5e 44 20 69 73 20 65 69 74 68 65 72 20  .  ^D is either 
2f800 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
2f810 72 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  r.** a pointer t
2f820 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  o a destructor f
2f830 75 6e 63 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e  unction for P. ^
2f840 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2f850 6b 65 20 74 68 65 0a 2a 2a 20 64 65 73 74 72 75  ke the.** destru
2f860 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69  ctor D with a si
2f870 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
2f880 20 50 20 77 68 65 6e 20 69 74 20 69 73 20 66 69   P when it is fi
2f890 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
2f8a0 50 2e 20 20 54 68 65 20 54 20 70 61 72 61 6d 65  P.  The T parame
2f8b0 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ter should be a 
2f8c0 73 74 61 74 69 63 20 73 74 72 69 6e 67 2c 20 70  static string, p
2f8d0 72 65 66 65 72 61 62 6c 79 20 61 20 73 74 72 69  referably a stri
2f8e0 6e 67 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54  ng.** literal. T
2f8f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f900 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 74 69 6e  pointer() routin
2f910 65 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  e is part of the
2f920 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72 20 70 61 73  .** [pointer pas
2f930 73 69 6e 67 20 69 6e 74 65 72 66 61 63 65 5d 20  sing interface] 
2f940 61 64 64 65 64 20 66 6f 72 20 53 51 4c 69 74 65  added for SQLite
2f950 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e   3.20.0..**.** ^
2f960 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
2f970 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2f980 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2f990 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
2f9a0 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
2f9b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f9c0 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
2f9d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2f9e0 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
2f9f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2fa00 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
2fa10 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
2fa20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
2fa30 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
2fa40 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
2fa50 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
2fa60 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
2fa70 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
2fa80 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
2fa90 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
2faa0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2fab0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2fac0 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
2fad0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2fae0 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
2faf0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
2fb00 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
2fb10 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
2fb20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
2fb30 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
2fb40 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
2fb50 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
2fb60 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2fb70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
2fb80 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2fb90 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2fba0 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
2fbb0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
2fbc0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
2fbd0 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
2fbe0 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62  _TOOBIG] might b
2fbf0 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
2fc00 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69  e size of a stri
2fc10 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78  ng or BLOB.** ex
2fc20 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70  ceeds limits imp
2fc30 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
2fc40 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2fc50 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f  LIMIT_LENGTH]) o
2fc60 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  r.** [SQLITE_MAX
2fc70 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53  _LENGTH]..** ^[S
2fc80 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
2fc90 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2fca0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
2fcb0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2fcc0 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
2fcd0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
2fce0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
2fcf0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
2fd00 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2fd10 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2fd20 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2fd30 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2fd40 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
2fd50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2fd60 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2fd70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2fd80 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
2fd90 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2fda0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
2fdb0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2fdc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2fdd0 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
2fde0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2fdf0 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
2fe00 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2fe10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fe20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2fe30 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2fe40 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
2fe50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2fe60 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
2fe70 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
2fe80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2fe90 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
2fea0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
2feb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2fec0 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
2fed0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2fee0 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
2fef0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
2ff00 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2ff10 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2ff20 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
2ff30 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  *,int,void(*)(vo
2ff40 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2ff50 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
2ff60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ff70 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2ff80 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2ff90 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2ffa0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71  3_bind_text64(sq
2ffb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ffc0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
2ffd0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2ffe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fff0 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
30000 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
30010 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
30020 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30030 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
30040 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
30050 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
30060 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
30070 69 6e 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69  ind_pointer(sqli
30080 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
30090 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
300a0 72 2a 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  r*,void(*)(void*
300b0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
300c0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
300d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
300e0 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71  , int n);.int sq
300f0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
30100 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
30110 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
30120 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  3_uint64);../*.*
30130 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
30140 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
30150 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ters.** METHOD: 
30160 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
30170 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
30180 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
30190 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
301a0 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
301b0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
301c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
301d0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
301e0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
301f0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
30200 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
30210 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
30220 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
30230 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
30240 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
30250 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
30260 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
30270 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
30280 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
30290 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
302a0 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
302b0 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
302c0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
302d0 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
302e0 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
302f0 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
30300 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
30310 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
30320 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
30330 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
30340 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
30350 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
30360 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
30370 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
30380 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
30390 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
303a0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
303b0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
303c0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
303d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
303e0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
303f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30400 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
30410 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
30420 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30430 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
30440 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
30450 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
30460 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
30470 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ter.** METHOD: s
30480 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
30490 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
304a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
304b0 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
304c0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
304d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
304e0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
304f0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
30500 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
30510 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
30520 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
30530 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
30540 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
30550 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
30560 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
30570 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
30580 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
30590 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
305a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
305b0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
305c0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
305d0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
305e0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
305f0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
30600 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
30610 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
30620 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
30630 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
30640 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
30650 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
30660 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
30670 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
30680 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
30690 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
306a0 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
306b0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
306c0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
306d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
306e0 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
306f0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
30700 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
30710 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
30720 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
30730 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
30740 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
30750 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
30760 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
30770 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
30780 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
30790 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
307a0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
307b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
307c0 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  6()],.** [sqlite
307d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
307e0 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  ], or [sqlite3_p
307f0 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a  repare16_v3()]..
30800 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
30810 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
30820 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
30830 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
30840 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
30850 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
30860 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30870 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
30880 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
30890 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
308a0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
308b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
308c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
308d0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
308e0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
308f0 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54  iven Name.** MET
30900 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30910 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
30920 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
30930 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
30940 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
30950 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
30960 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
30970 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
30980 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
30990 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
309a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
309b0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
309c0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
309d0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
309e0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
309f0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
30a00 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
30a10 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
30a20 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
30a30 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
30a40 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
30a50 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
30a60 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
30a70 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
30a80 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  re16_v2()] or.**
30a90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30aa0 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v3()]..**.**
30ab0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
30ac0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
30ad0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
30ae0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
30af0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
30b00 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
30b10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30b20 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69  er_name()]..*/.i
30b30 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30b40 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
30b50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
30b60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
30b70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30b80 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
30b90 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
30ba0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
30bb0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
30bc0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  3_stmt.**.** ^Co
30bd0 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
30be0 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
30bf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30c00 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
30c10 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
30c20 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
30c30 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
30c40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30c50 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
30c60 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
30c70 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
30c80 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
30c90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
30ca0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
30cb0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
30cc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
30cd0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
30ce0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
30cf0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
30d00 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
30d10 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
30d20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
30d30 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
30d40 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
30d50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30d60 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72  ent]. ^If this r
30d70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
30d80 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
30d90 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
30da0 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e  tatement] return
30db0 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65  s no data (for e
30dc0 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
30dd0 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72  E])..** ^However
30de0 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 74  , just because t
30df0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
30e00 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
30e10 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a  umber does not.*
30e20 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20  * mean that one 
30e30 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20  or more rows of 
30e40 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74  data will be ret
30e50 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43  urned.  ^A SELEC
30e60 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  T statement.** w
30e70 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20  ill always have 
30e80 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74  a positive sqlit
30e90 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
30ea0 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20  ) but depending 
30eb0 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20  on the.** WHERE 
30ec0 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
30ed0 74 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65  ts and the table
30ee0 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67   content, it mig
30ef0 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77  ht return no row
30f00 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
30f10 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
30f20 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
30f30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30f40 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
30f50 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30f60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
30f70 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
30f80 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54  esult Set.** MET
30f90 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30fa0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
30fb0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
30fc0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
30fd0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
30fe0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
30ff0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
31000 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
31010 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
31020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
31030 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
31040 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
31050 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
31060 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
31070 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
31080 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
31090 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
310a0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
310b0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
310c0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
310d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
310e0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
310f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
31100 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
31110 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
31120 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
31130 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
31140 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
31150 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
31160 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
31170 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
31180 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
31190 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
311a0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
311b0 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
311c0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
311d0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
311e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
311f0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
31200 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
31210 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
31220 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
31230 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
31240 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31250 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
31260 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
31270 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
31280 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
31290 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
312a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
312b0 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
312c0 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
312d0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
312e0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
312f0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
31300 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
31310 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
31320 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
31330 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
31340 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
31350 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
31360 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
31370 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
31380 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
31390 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
313a0 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
313b0 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
313c0 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
313d0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
313e0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
313f0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
31400 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
31410 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
31420 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
31430 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
31440 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
31450 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
31460 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
31470 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
31480 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
31490 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
314a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
314b0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
314c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
314d0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
314e0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
314f0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
31500 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
31510 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
31520 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
31530 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
31540 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
31550 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
31560 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
31570 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
31580 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
31590 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
315a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
315b0 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
315c0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
315d0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
315e0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
315f0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
31600 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
31610 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
31620 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
31630 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
31640 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
31650 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
31660 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
31670 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
31680 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
31690 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
316a0 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
316b0 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
316c0 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
316d0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
316e0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
316f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31700 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
31710 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
31720 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
31730 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
31740 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
31750 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
31760 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
31770 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
31780 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
31790 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
317a0 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
317b0 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
317c0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
317d0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
317e0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
317f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
31800 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
31810 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
31820 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
31830 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
31840 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
31850 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
31860 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
31870 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
31880 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
31890 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
318a0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
318b0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
318c0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
318d0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
318e0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
318f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
31900 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
31910 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
31920 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
31930 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
31940 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
31950 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
31960 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
31970 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
31980 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
31990 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
319a0 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
319b0 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
319c0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
319d0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
319e0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
319f0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
31a00 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
31a10 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
31a20 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
31a30 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
31a40 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
31a50 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
31a60 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
31a70 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
31a80 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
31a90 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
31aa0 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
31ab0 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
31ac0 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
31ad0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
31ae0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
31af0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
31b00 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
31b10 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
31b20 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
31b30 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
31b40 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
31b50 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
31b60 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
31b70 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
31b80 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
31b90 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
31ba0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
31bb0 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
31bc0 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
31bd0 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
31be0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
31bf0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
31c00 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
31c10 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
31c20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
31c30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
31c40 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
31c50 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
31c60 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
31c70 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
31c80 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
31c90 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
31ca0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
31cb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
31cc0 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
31cd0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
31ce0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
31cf0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
31d00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31d10 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
31d20 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
31d30 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
31d40 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
31d50 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
31d60 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
31d70 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
31d80 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31d90 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
31da0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31db0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
31dc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
31dd0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
31de0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31df0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
31e00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31e10 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31e20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
31e30 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
31e40 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
31e50 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
31e60 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
31e70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31e80 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
31e90 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31ea0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
31eb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
31ec0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31ed0 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
31ee0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
31ef0 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
31f00 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31f10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
31f20 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
31f30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31f40 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
31f50 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
31f60 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
31f70 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
31f80 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
31f90 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
31fa0 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
31fb0 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
31fc0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
31fd0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
31fe0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
31ff0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
32000 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
32010 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
32020 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
32030 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
32040 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
32050 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
32060 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
32070 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
32080 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
32090 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
320a0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
320b0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
320c0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
320d0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
320e0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
320f0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
32100 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
32110 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
32120 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
32130 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
32140 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
32150 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
32160 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
32170 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
32180 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
32190 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
321a0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
321b0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
321c0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
321d0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
321e0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
321f0 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
32200 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
32210 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
32220 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
32230 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
32240 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
32250 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
32260 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
32270 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
32280 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
32290 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
322a0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
322b0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
322c0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
322d0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
322e0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
322f0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
32300 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
32310 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
32320 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
32330 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
32340 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
32350 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
32360 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
32370 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
32380 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
32390 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
323a0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
323b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
323c0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
323d0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
323e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
323f0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
32400 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
32410 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
32420 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
32430 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32440 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
32450 61 72 65 64 20 75 73 69 6e 67 20 61 6e 79 20 6f  ared using any o
32460 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  f.** [sqlite3_pr
32470 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
32480 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
32490 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
324a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a  epare16_v2()],.*
324b0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  * or [sqlite3_pr
324c0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 6f 72  epare16_v3()] or
324d0 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
324e0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
324f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32500 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
32510 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
32520 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
32530 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
32540 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
32550 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
32560 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
32570 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
32580 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
32590 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
325a0 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
325b0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
325c0 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
325d0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
325e0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
325f0 58 22 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  X" interfaces.**
32600 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32610 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v3()], [sqlite
32620 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
32630 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32640 65 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73  e16_v3()],.** [s
32650 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32660 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
32670 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
32680 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
32690 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
326a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
326b0 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
326c0 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
326d0 76 58 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  vX" interface is
326e0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
326f0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
32700 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
32710 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
32720 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
32730 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
32740 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
32750 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
32760 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
32770 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
32780 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
32790 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
327a0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
327b0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
327c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
327d0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
327e0 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
327f0 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
32800 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
32810 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
32820 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
32830 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
32840 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
32850 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
32860 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
32870 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
32880 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
32890 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
328a0 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
328b0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
328c0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
328d0 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
328e0 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
328f0 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
32900 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
32910 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
32920 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
32930 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
32940 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
32950 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
32960 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
32970 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
32980 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
32990 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
329a0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
329b0 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
329c0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
329d0 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
329e0 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
329f0 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
32a00 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
32a10 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
32a20 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
32a30 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
32a40 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
32a50 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
32a60 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
32a70 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
32a80 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
32a90 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
32aa0 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
32ab0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
32ac0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
32ad0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
32ae0 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
32af0 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
32b00 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
32b10 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
32b20 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
32b30 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
32b40 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
32b50 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
32b60 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
32b70 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
32b80 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
32b90 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
32ba0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
32bb0 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
32bc0 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
32bd0 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
32be0 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
32bf0 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
32c00 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
32c10 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
32c20 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
32c30 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
32c40 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
32c50 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
32c60 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
32c70 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
32c80 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
32c90 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
32ca0 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
32cb0 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
32cc0 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
32cd0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
32ce0 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
32cf0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
32d00 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
32d10 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
32d20 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
32d30 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
32d40 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
32d50 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
32d60 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
32d70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
32d80 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
32d90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32da0 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
32db0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
32dc0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
32dd0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
32de0 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
32df0 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
32e00 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
32e10 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
32e20 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
32e30 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
32e40 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
32e50 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
32e60 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
32e70 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
32e80 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
32e90 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
32ea0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
32eb0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
32ec0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
32ed0 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
32ee0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
32ef0 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
32f00 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
32f10 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
32f20 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
32f30 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
32f40 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
32f50 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
32f60 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
32f70 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
32f80 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
32f90 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
32fa0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
32fb0 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
32fc0 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
32fd0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
32fe0 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
32ff0 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
33000 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
33010 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
33020 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
33030 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
33040 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
33050 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
33060 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
33070 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
33080 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
33090 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
330a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
330b0 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
330c0 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
330d0 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
330e0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
330f0 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
33100 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e  er [version 3.6.
33110 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33  23.1] ([dateof:3
33120 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c  .6.23.1],.** sql
33130 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
33140 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
33150 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
33160 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
33170 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
33180 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
33190 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
331a0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
331b0 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
331c0 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
331d0 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
331e0 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
331f0 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
33200 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
33210 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
33220 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
33230 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
33240 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
33250 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
33260 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
33270 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
33280 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
33290 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
332a0 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
332b0 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
332c0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
332d0 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
332e0 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
332f0 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
33300 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
33310 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
33320 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
33330 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
33340 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
33350 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
33360 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
33370 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
33380 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
33390 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
333a0 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
333b0 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
333c0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
333d0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
333e0 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
333f0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
33400 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
33410 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
33420 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
33430 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
33440 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
33450 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
33460 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
33470 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
33480 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
33490 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
334a0 70 61 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73  pare_v3()] or [s
334b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
334c0 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  2()].** or [sqli
334d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
334e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
334f0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
33500 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
33510 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
33520 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
33530 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33540 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
33550 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
33560 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
33570 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
33580 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
33590 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
335a0 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
335b0 6f 66 20 74 68 65 20 22 76 58 22 20 69 6e 74 65  of the "vX" inte
335c0 72 66 61 63 65 73 20 69 73 20 72 65 63 6f 6d 6d  rfaces is recomm
335d0 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
335e0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
335f0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
33600 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
33610 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
33620 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
33630 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33640 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
33650 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
33660 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
33670 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
33680 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
33690 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
336a0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
336b0 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
336c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
336d0 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
336e0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
336f0 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
33700 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
33710 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
33720 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
33730 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
33740 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
33750 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
33760 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
33770 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
33780 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
33790 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
337a0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
337b0 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
337c0 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
337d0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
337e0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
337f0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
33800 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
33810 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
33820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
33830 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
33840 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
33850 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
33860 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
33870 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
33880 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
33890 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
338a0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
338b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
338c0 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
338d0 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
338e0 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
338f0 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
33900 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
33910 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
33920 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
33930 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
33940 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
33950 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
33960 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
33970 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
33980 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
33990 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
339a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
339b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
339c0 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
339d0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
339e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
339f0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
33a00 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
33a10 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
33a20 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
33a30 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
33a40 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
33a50 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
33a60 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
33a70 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
33a80 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
33a90 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
33aa0 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
33ab0 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
33ac0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
33ad0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
33ae0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
33af0 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
33b00 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
33b10 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
33b20 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
33b30 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
33b40 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
33b50 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
33b60 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
33b70 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
33b80 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
33b90 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
33ba0 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
33bb0 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
33bc0 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
33bd0 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
33be0 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
33bf0 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
33c00 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
33c10 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
33c20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
33c30 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
33c40 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
33c50 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
33c60 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
33c70 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
33c80 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
33c90 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
33ca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
33cb0 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
33cc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
33cd0 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
33ce0 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
33cf0 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
33d00 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
33d10 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
33d20 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e  3_stmt.**.** <b>
33d30 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20  Summary:</b>.** 
33d40 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62  <blockquote><tab
33d50 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c  le border=0 cell
33d60 70 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70  padding=0 cellsp
33d70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e  acing=0>.** <tr>
33d80 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
33d90 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74  olumn_blob</b><t
33da0 64 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42  d>&rarr;<td>BLOB
33db0 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
33dc0 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
33dd0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c  lumn_double</b><
33de0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41  td>&rarr;<td>REA
33df0 4c 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  L result.** <tr>
33e00 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
33e10 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64  olumn_int</b><td
33e20 3e 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69  >&rarr;<td>32-bi
33e30 74 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74  t INTEGER result
33e40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
33e50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
33e60 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  t64</b><td>&rarr
33e70 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45  ;<td>64-bit INTE
33e80 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  GER result.** <t
33e90 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
33ea0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e  _column_text</b>
33eb0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54  <td>&rarr;<td>UT
33ec0 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a  F-8 TEXT result.
33ed0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
33ee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33ef0 74 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  t16</b><td>&rarr
33f00 3b 3c 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54  ;<td>UTF-16 TEXT
33f10 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c   result.** <tr><
33f20 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
33f30 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74  lumn_value</b><t
33f40 64 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20  d>&rarr;<td>The 
33f50 72 65 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a  result as an .**
33f60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c   [sqlite3_value|
33f70 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
33f80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33f90 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e  t..** <tr><td>&n
33fa0 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74  bsp;<td>&nbsp;<t
33fb0 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e  d>&nbsp;.** <tr>
33fc0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
33fd0 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c  olumn_bytes</b><
33fe0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a  td>&rarr;<td>Siz
33ff0 65 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f  e of a BLOB.** o
34000 72 20 61 20 55 54 46 2d 38 20 54 45 58 54 20 72  r a UTF-8 TEXT r
34010 65 73 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a  esult in bytes.*
34020 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
34030 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34040 73 31 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c  s16&nbsp;&nbsp;<
34050 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72  /b>.** <td>&rarr
34060 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64  ;&nbsp;&nbsp;<td
34070 3e 53 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a  >Size of UTF-16.
34080 2a 2a 20 54 45 58 54 20 69 6e 20 62 79 74 65 73  ** TEXT in bytes
34090 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
340a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
340b0 70 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  pe</b><td>&rarr;
340c0 3c 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64  <td>Default.** d
340d0 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72  atatype of the r
340e0 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65  esult.** </table
340f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
34100 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a  *.** <b>Details:
34110 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  </b>.**.** ^Thes
34120 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
34130 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
34140 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
34150 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
34160 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
34170 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
34180 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
34190 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
341a0 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
341b0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
341c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
341d0 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
341e0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
341f0 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
34200 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
34210 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
34220 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
34230 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
34240 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
34250 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
34260 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
34270 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
34280 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
34290 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
342a0 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
342b0 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
342c0 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
342d0 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
342e0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
342f0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
34300 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
34310 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
34320 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
34330 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
34340 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
34350 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
34360 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
34370 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
34380 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
34390 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
343a0 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
343b0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
343c0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
343d0 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
343e0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
343f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
34400 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
34410 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
34420 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
34430 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
34440 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34450 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
34460 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
34470 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
34480 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
34490 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
344a0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
344b0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
344c0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
344d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
344e0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
344f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
34500 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
34510 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
34520 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
34530 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
34540 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
34550 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
34560 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
34570 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
34580 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
34590 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
345a0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
345b0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
345c0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
345d0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
345e0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
345f0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
34600 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  d..**.** The fir
34610 73 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65  st six interface
34620 73 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c  s (_blob, _doubl
34630 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c  e, _int, _int64,
34640 20 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78   _text, and _tex
34650 74 31 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74  t16).** each ret
34660 75 72 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  urn the value of
34670 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
34680 20 69 6e 20 61 20 73 70 65 63 69 66 69 63 20 64   in a specific d
34690 61 74 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a  ata format.  If.
346a0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  ** the result co
346b0 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74  lumn is not init
346c0 69 61 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71  ially in the req
346d0 75 65 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66  uested format (f
346e0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
346f0 66 20 74 68 65 20 71 75 65 72 79 20 72 65 74 75  f the query retu
34700 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62  rns an integer b
34710 75 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ut the sqlite3_c
34720 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74  olumn_text() int
34730 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65  erface.** is use
34740 64 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65  d to extract the
34750 20 76 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20   value) then an 
34760 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63  automatic type c
34770 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
34780 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  formed..**.** ^T
34790 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
347a0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
347b0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
347c0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
347d0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
347e0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
347f0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
34800 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
34810 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
34820 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
34830 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
34840 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
34850 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
34860 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
34870 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
34880 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72  _NULL]..** The r
34890 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73  eturn value of s
348a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
348b0 70 65 28 29 20 63 61 6e 20 62 65 20 75 73 65 64  pe() can be used
348c0 20 74 6f 20 64 65 63 69 64 65 20 77 68 69 63 68   to decide which
348d0 0a 2a 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74  .** of the first
348e0 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 20 73   six interface s
348f0 68 6f 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f  hould be used to
34900 20 65 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c   extract the col
34910 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68  umn value..** Th
34920 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
34930 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
34940 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
34950 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
34960 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20  no.** automatic 
34970 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
34980 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 66   have occurred f
34990 6f 72 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20  or the value in 
349a0 71 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41  question.  .** A
349b0 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
349c0 65 72 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75  ersion, the resu
349d0 6c 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71  lt of calling sq
349e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
349f0 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  e().** is undefi
34a00 6e 65 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d  ned, though harm
34a10 6c 65 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a  less.  Future.**
34a20 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
34a30 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
34a40 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
34a50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
34a60 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
34a70 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
34a80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
34a90 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
34aa0 4f 42 20 6f 72 20 61 20 54 45 58 54 20 73 74 72  OB or a TEXT str
34ab0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ing, then the sq
34ac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34ad0 65 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  es().** or sqlit
34ae0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
34af0 36 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 63  6() interfaces c
34b00 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
34b10 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65  termine the size
34b20 0a 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42  .** of that BLOB
34b30 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a   or string..**.*
34b40 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
34b50 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
34b60 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
34b70 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
34b80 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
34b90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
34ba0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34bb0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
34bc0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
34bd0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34be0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
34bf0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
34c00 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
34c10 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
34c20 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
34c30 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
34c40 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
34c50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
34c60 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
34c70 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
34c80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34c90 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
34ca0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
34cb0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
34cc0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
34cd0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
34ce0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
34cf0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
34d00 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
34d10 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34d20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
34d30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
34d40 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
34d50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
34d60 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
34d70 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
34d80 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
34d90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34da0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
34db0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
34dc0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
34dd0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
34de0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
34df0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
34e00 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
34e10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
34e20 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
34e30 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
34e40 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
34e50 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
34e60 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
34e70 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34e80 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
34e90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
34ea0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
34eb0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
34ec0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
34ed0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
34ee0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
34ef0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
34f00 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
34f10 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
34f20 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
34f30 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
34f40 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
34f50 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
34f60 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
34f70 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
34f80 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
34f90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34fa0 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
34fb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34fc0 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
34fd0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
34fe0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
34ff0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
35000 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
35010 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
35020 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
35030 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
35040 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
35050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35060 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
35070 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
35080 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
35090 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
350a0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
350b0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
350c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
350d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
350e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
350f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
35100 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
35110 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
35120 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
35130 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
35140 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
35150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
35160 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
35170 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
35180 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
35190 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c  .** <b>Warning:<
351a0 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  /b> ^The object 
351b0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
351c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
351d0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
351e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
351f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35200 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72  .  In a multithr
35210 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e  eaded environmen
35220 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65  t,.** an unprote
35230 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
35240 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e  ue object may on
35250 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c  ly be used safel
35260 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  y with.** [sqlit
35270 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
35280 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
35290 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
352a0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
352b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
352c0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
352d0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
352e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
352f0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
35300 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
35310 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
35320 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
35330 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
35340 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
35350 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
35360 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
35370 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
35380 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
35390 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a  not threadsafe..
353a0 2a 2a 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71  ** Hence, the sq
353b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
353c0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ue() interface.*
353d0 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e  * is normally on
353e0 6c 79 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e  ly useful within
353f0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
35400 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c  ion of .** [appl
35410 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35420 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
35430 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
35440 73 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a  s], not within.*
35450 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c  * top-level appl
35460 69 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a  ication code..**
35470 0a 2a 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f  .** The these ro
35480 75 74 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d  utines may attem
35490 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
354a0 65 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68  e datatype of th
354b0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f  e result..** ^Fo
354c0 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  r example, if th
354d0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
354e0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
354f0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
35500 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
35510 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
35520 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
35530 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
35540 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
35550 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
35560 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
35570 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
35580 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
35590 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
355a0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
355b0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
355c0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
355d0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
355e0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
355f0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
35600 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
35610 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
35620 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
35630 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
35640 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
35650 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
35660 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
35670 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
35680 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
35690 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
356a0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
356b0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
356c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
356d0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
356e0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
356f0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
35700 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
35710 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
35720 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
35730 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
35740 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
35750 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
35760 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
35770 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
35780 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
35790 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
357a0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
357b0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
357c0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
357d0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
357e0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
357f0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
35800 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
35810 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
35820 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
35830 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
35840 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
35850 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
35860 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
35870 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
35880 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
35890 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
358a0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
358b0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
358c0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
358d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
358e0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
358f0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
35900 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
35910 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
35920 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
35930 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
35940 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
35950 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
35960 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
35970 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
35980 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
35990 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
359a0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
359b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
359c0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
359d0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
359e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
359f0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
35a00 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
35a10 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ote>)^.**.** Not
35a20 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
35a30 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
35a40 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
35a50 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
35a60 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
35a70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
35a80 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
35a90 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
35aa0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
35ab0 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
35ac0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
35ad0 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
35ae0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
35af0 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
35b00 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
35b10 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
35b20 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
35b30 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
35b40 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
35b50 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
35b60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
35b70 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
35b80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
35b90 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
35ba0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
35bb0 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
35bc0 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
35bd0 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
35be0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
35bf0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
35c00 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
35c10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35c20 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
35c30 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
35c40 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
35c50 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
35c60 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
35c70 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
35c80 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
35c90 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
35ca0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
35cb0 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
35cc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35cd0 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
35ce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35cf0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
35d00 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
35d10 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
35d20 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
35d30 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
35d40 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
35d50 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
35d60 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
35d70 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
35d80 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
35d90 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
35da0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
35db0 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
35dc0 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
35dd0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
35de0 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
35df0 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
35e00 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
35e10 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
35e20 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
35e30 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
35e40 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
35e50 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
35e60 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
35e70 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
35e80 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
35e90 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
35ea0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
35eb0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
35ec0 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c  * The safest pol
35ed0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
35ee0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
35ef0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
35f00 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
35f10 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
35f20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
35f30 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
35f40 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
35f50 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
35f60 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
35f70 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
35f80 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
35f90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35fa0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
35fb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35fc0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
35fd0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
35fe0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
35ff0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
36000 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
36010 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
36020 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36030 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
36040 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
36050 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
36060 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
36070 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
36080 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
36090 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
360a0 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
360b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
360c0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
360d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
360e0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
360f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
36100 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
36110 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
36120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36130 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
36140 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
36150 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
36160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36170 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
36180 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
36190 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
361a0 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
361b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
361c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
361d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
361e0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
361f0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
36200 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
36210 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
36220 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
36230 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
36240 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
36250 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
36260 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
36270 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
36280 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
36290 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
362a0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
362b0 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
362c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
362d0 44 6f 20 6e 6f 74 20 70 61 73 73 20 74 68 65 20  Do not pass the 
362e0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
362f0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
36300 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
36310 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
36320 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
36330 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
36340 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
36350 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
36360 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
36370 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
36380 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
36390 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
363a0 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
363b0 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
363c0 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
363d0 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
363e0 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
363f0 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
36400 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
36410 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
36420 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
36430 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
36440 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
36450 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
36460 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
36470 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
36480 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
36490 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
364a0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
364b0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
364c0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
364d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
364e0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
364f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
36500 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36510 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
36520 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
36530 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
36540 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36550 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
36560 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
36570 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
36580 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36590 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
365a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
365b0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
365c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
365d0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
365e0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
365f0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
36600 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36610 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
36620 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
36630 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36640 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
36650 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
36660 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
36670 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
36680 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36690 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
366a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
366b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
366c0 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
366d0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
366e0 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52  ct.** DESTRUCTOR
366f0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
36700 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36710 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
36720 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
36730 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
36740 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36750 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
36760 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
36770 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
36780 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
36790 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
367a0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
367b0 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
367c0 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
367d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
367e0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
367f0 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
36800 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
36810 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
36820 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
36830 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
36840 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
36850 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
36860 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
36870 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
36880 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
36890 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
368a0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
368b0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
368c0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
368d0 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
368e0 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
368f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36900 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
36910 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
36920 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
36930 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
36940 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
36950 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
36960 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
36970 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
36980 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
36990 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
369a0 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
369b0 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
369c0 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
369d0 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
369e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
369f0 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
36a00 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
36a10 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
36a20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
36a30 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
36a40 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
36a50 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
36a60 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
36a70 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
36a80 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
36a90 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
36aa0 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
36ab0 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
36ac0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
36ad0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
36ae0 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
36af0 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
36b00 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
36b10 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
36b20 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
36b30 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
36b40 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
36b50 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
36b60 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
36b70 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
36b80 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
36b90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
36ba0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
36bb0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
36bc0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
36bd0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
36be0 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44  Object.** METHOD
36bf0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
36c00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
36c10 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
36c20 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
36c30 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
36c40 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
36c50 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
36c60 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
36c70 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
36c80 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
36c90 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
36ca0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
36cb0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
36cc0 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
36cd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
36ce0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
36cf0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
36d00 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
36d10 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
36d20 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
36d30 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
36d40 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
36d50 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
36d60 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
36d70 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
36d80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36d90 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
36da0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
36db0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
36dc0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
36dd0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
36de0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
36df0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
36e00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36e10 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
36e20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
36e30 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
36e40 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
36e50 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
36e60 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
36e70 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
36e80 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
36e90 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
36ea0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
36eb0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
36ec0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
36ed0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
36ee0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
36ef0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36f00 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
36f10 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
36f20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
36f30 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
36f40 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
36f50 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
36f60 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
36f70 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
36f80 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
36f90 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
36fa0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
36fb0 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
36fc0 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
36fd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
36fe0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
36ff0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
37000 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
37010 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
37020 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
37030 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
37040 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
37050 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
37060 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
37070 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
37080 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
37090 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
370a0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
370b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
370c0 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
370d0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
370e0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
370f0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
37100 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
37110 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
37120 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
37130 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
37140 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
37150 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
37160 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
37170 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
37180 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
37190 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
371a0 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
371b0 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
371c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
371d0 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
371e0 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
371f0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
37200 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
37210 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
37220 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
37230 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
37240 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
37250 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
37260 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
37270 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37280 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
37290 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
372a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
372b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
372c0 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
372d0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
372e0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
372f0 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
37300 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
37310 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
37320 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
37330 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
37340 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
37350 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
37360 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
37370 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
37380 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
37390 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
373a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
373b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
373c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
373d0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
373e0 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
373f0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
37400 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
37410 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
37420 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
37430 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
37440 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
37450 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
37460 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
37470 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
37480 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
37490 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
374a0 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
374b0 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
374c0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
374d0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
374e0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
374f0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
37500 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
37510 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
37520 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
37530 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
37540 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
37550 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
37560 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
37570 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
37580 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
37590 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
375a0 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
375b0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
375c0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
375d0 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
375e0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
375f0 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
37600 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
37610 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
37620 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
37630 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
37640 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
37650 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
37660 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
37670 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
37680 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
37690 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
376a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
376b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
376c0 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
376d0 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
376e0 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
376f0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
37700 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
37710 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
37720 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20  arameters.  The 
37730 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
37740 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61  ld set this para
37750 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c  meter to.** [SQL
37760 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20  ITE_UTF16LE] if 
37770 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
37780 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
37790 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  kes .** [sqlite3
377a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
377b0 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20  )] on an input, 
377c0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
377d0 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d  BE] if the.** im
377e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
377f0 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61  okes [sqlite3_va
37800 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20  lue_text16be()] 
37810 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a  on an input, or.
37820 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
37830 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  ] if [sqlite3_va
37840 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73  lue_text16()] is
37850 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54   used, or [SQLIT
37860 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72  E_UTF8].** other
37870 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65  wise.  ^The same
37880 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61   SQL function ma
37890 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
378a0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
378b0 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e  sing.** differen
378c0 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  t preferred text
378d0 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68   encodings, with
378e0 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65   different imple
378f0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a  mentations for.*
37900 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e  * each encoding.
37910 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
37920 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
37930 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
37940 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
37950 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
37960 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
37970 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
37980 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
37990 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
379a0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sion..**.** ^The
379b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
379c0 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79  r may optionally
379d0 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53   be ORed with [S
379e0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
379f0 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  TIC].** to signa
37a00 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74  l that the funct
37a10 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ion will always 
37a20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
37a30 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20  result given.** 
37a40 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20  the same inputs 
37a50 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20  within a single 
37a60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
37a70 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  Most SQL functio
37a80 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d  ns are.** determ
37a90 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75  inistic.  The bu
37aa0 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29  ilt-in [random()
37ab0 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  ] SQL function i
37ac0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
37ad0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  a.** function th
37ae0 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d  at is not determ
37af0 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51  inistic.  The SQ
37b00 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e  Lite query plann
37b10 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a  er is able to.**
37b20 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f   perform additio
37b30 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  nal optimization
37b40 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74  s on determinist
37b50 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f  ic functions, so
37b60 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b   use.** of the [
37b70 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
37b80 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65  STIC] flag is re
37b90 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20  commended where 
37ba0 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  possible..**.** 
37bb0 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
37bc0 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
37bd0 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
37be0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
37bf0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
37c00 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
37c10 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
37c20 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
37c30 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
37c40 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ].)^.**.** ^The 
37c50 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61  sixth, seventh a
37c60 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65  nd eighth parame
37c70 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
37c80 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
37c90 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
37ca0 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
37cb0 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
37cc0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
37cd0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
37ce0 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
37cf0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
37d00 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
37d10 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
37d20 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
37d30 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
37d40 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70  inters must be p
37d50 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
37d60 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
37d70 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
37d80 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
37d90 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
37da0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
37db0 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
37dc0 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
37dd0 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20  LL pointer must 
37de0 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
37df0 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
37e00 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
37e10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
37e20 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
37e30 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72  ULL pointers for
37e40 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
37e50 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73  ion.** callbacks
37e60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65  ..**.** ^(If the
37e70 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
37e80 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
37e90 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
37ea0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
37eb0 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74   then it is dest
37ec0 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61  ructor for the a
37ed0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
37ee0 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65  pointer. .** The
37ef0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69   destructor is i
37f00 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
37f10 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
37f20 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62  ted, either by b
37f30 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64  eing.** overload
37f40 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64  ed or when the d
37f50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37f60 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20  on closes.)^.** 
37f70 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
37f80 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20  is also invoked 
37f90 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  if the call to.*
37fa0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
37fb0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66  _function_v2() f
37fc0 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74  ails..** ^When t
37fd0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61  he destructor ca
37fe0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65  llback of the te
37ff0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  nth parameter is
38000 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20   invoked, it.** 
38010 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67  is passed a sing
38020 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
38030 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  h is a copy of t
38040 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
38050 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ata .** pointer 
38060 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69  which was the fi
38070 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  fth parameter to
38080 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38090 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  function_v2()..*
380a0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
380b0 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
380c0 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
380d0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
380e0 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
380f0 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
38100 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
38110 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
38120 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
38130 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
38140 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
38150 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
38160 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
38170 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
38180 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
38190 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
381a0 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
381b0 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
381c0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
381d0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
381e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
381f0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
38200 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
38210 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
38220 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
38230 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
38240 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
38250 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
38260 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
38270 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
38280 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
38290 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
382a0 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
382b0 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
382c0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
382d0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
382e0 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
382f0 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
38300 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
38310 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
38320 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
38330 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
38340 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
38350 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
38360 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
38370 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
38380 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
38390 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
383a0 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
383b0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
383c0 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
383d0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
383e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
383f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70  s..**.** ^An app
38400 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
38410 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
38420 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
38430 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
38440 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
38450 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
38460 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
38470 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
38480 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
38490 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
384a0 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
384b0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
384c0 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
384d0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69  is running..*/.i
384e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
384f0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
38500 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
38510 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
38520 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
38530 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
38540 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
38550 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
38560 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
38570 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
38580 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
38590 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
385a0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
385b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
385c0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
385d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
385e0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
385f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
38600 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
38610 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
38620 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
38630 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
38640 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
38650 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
38660 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
38670 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
38680 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
38690 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
386a0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
386b0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
386c0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
386d0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
386e0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
386f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
38700 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
38710 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
38720 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
38730 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
38740 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
38750 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
38760 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
38770 75 6e 63 29 28 73 71 6c 6